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

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:

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:

# 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}'