> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getagentdrive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Folders

> Flat path-based file organization

AgentDrive uses a **flat path-based model** (like S3), not a hierarchical filesystem. Folders are zero-byte marker files that end with `/`.

## How it works

* Files have a `path` property: `reports/q1/summary.pdf`
* Folders are created explicitly: `reports/` and `reports/q1/`
* Creating a folder automatically creates all parent folders
* Listing with a `delimiter` parameter returns virtual folder prefixes

## Creating folders

```bash theme={null}
curl -X POST https://api.getagentdrive.com/v0/folders \
  -H "Authorization: Bearer agd_your_key" \
  -H "Content-Type: application/json" \
  -d '{"drive_id": "YOUR_DRIVE_ID", "path": "reports/q1/"}'
```

This creates both `reports/` and `reports/q1/` if they don't exist.

## Listing folder contents

Use the `delimiter` parameter to list files at a specific level:

```bash theme={null}
curl "https://api.getagentdrive.com/v0/files?drive_id=ID&prefix=reports/&delimiter=/" \
  -H "Authorization: Bearer agd_your_key"
```

Returns direct files and sub-folder prefixes at the `reports/` level.

## Deleting folders

Folder deletion is recursive. A confirmation step is required:

```bash theme={null}
# Preview what will be deleted
curl -X DELETE https://api.getagentdrive.com/v0/folders \
  -H "Authorization: Bearer agd_your_key" \
  -d '{"drive_id": "ID", "path": "reports/q1/"}'

# Confirm deletion
curl -X DELETE https://api.getagentdrive.com/v0/folders \
  -H "Authorization: Bearer agd_your_key" \
  -d '{"drive_id": "ID", "path": "reports/q1/", "confirm": true}'
```