Folders

All endpoints below require the API-Key header.

Folder objects in responses have this shape:

{
  "id": "9c8b7a6d-...",
  "name": "demo",
  "key": "projects/demo",
  "parentId": "3e2d1c0b-...",
  "createdAt": "2026-07-15 12:00:00",
  "updatedAt": "2026-07-15 12:00:00"
}

key is the folder's path relative to the storage root. The root folder's key is the empty string.

Browse a folder

GET /api/folders
GET /api/folders?id=<folder-id>
GET /api/folders?key=<folder/key>

Returns the files and direct subfolders of a folder. With no id or key, the root folder is returned. The files list supports the list query parameters.

curl "https://files.example.com/api/folders?key=projects/demo&orderBy=name&orderDirection=ASC" \
  -H "API-Key: your-api-key"

{
  "data": {
    "files": [ ... ],
    "folders": [ ... ]
  },
  "error": null
}

Responds 404 when the folder doesn't exist. path is accepted as an alias for key.

Create a folder

POST /api/folders

JSON body — a path relative to the root folder; intermediate folders are created automatically:

{ "folder": "projects/demo/assets" }

{ "data": { "folder": { ... } }, "error": null }

Folder names may contain dots (release/v1.0 is fine). What is rejected with 400 is anything that could escape the storage root: the segments . and .., path separators inside a name, and NUL bytes. An existing folder responds 409.

Rename a folder or set visibility in bulk

PUT /api/folders

JSON body — name, visibility, or both. At least one is required:

{ "id": "<folder-id>", "name": "new-name" }

The new name must be a single path segment. Renaming also rewrites the keys of every file and subfolder inside. A sibling folder with the same name responds 409.

visibility cascades: it applies public or private to every file in the folder and all its subfolders, in one transaction.

{ "id": "<folder-id>", "visibility": "private" }

Folders do not themselves carry a visibility — this is a bulk write over the files beneath them, not an inherited setting, so a file uploaded afterwards takes the instance default rather than the folder's last cascade. Unlike rename, the root folder is a valid cascade target, which is how you lock down an entire instance in one call.

Delete a folder

DELETE /api/folders

JSON body:

{ "id": "<folder-id>" }

The root folder cannot be renamed or deleted — both respond 400. Removing it would take the entire storage tree with it. A visibility cascade against the root is allowed.