Folders

/api/v1 operations for folders. See HTTP API for authentication, the error envelope, and rate limits.

Operations

GET /api/v1/folders

List folders

Returns every active folder in the organization as a flat list with id, name, parent id, and path. Reconstruct the hierarchy from parentId, or address folders by path on the file endpoints.

Auth: API key required.

Operation ID: listFolders

Responses:

• 200 — The organization's active folders.
• 401 — Authentication is missing or invalid.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan folders list

POST /api/v1/folders

Create a folder

Creates a folder under the root, a parentId, or a parentPath (mutually exclusive; the parent must already exist). Sibling folder names are unique case-insensitively — a duplicate name responds 409.

Auth: API key required.

Operation ID: createFolder

Request body (application/json, required):

• name (string, required)
• parentId (string | null, optional)
• parentPath (string | null, optional) — Parent folder path; "/" or omitted creates under the root.

Responses:

• 201 — The created folder.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan folders create

PATCH /api/v1/folders/{folderId}

Rename a folder

Renames the folder. Descendant folder paths update automatically; previously stored paths into the subtree stop resolving, so store folder ids rather than paths. Sibling name conflicts respond 409.

Auth: API key required.

Operation ID: renameFolder

Path parameters:

• folderId (string, required)

Request body (application/json, required):

• name (string, required)

Responses:

• 200 — The renamed folder.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan folders rename

DELETE /api/v1/folders/{folderId}

Delete a folder

Soft-deletes an empty folder. A folder containing active child folders, ready files, or live pending uploads responds 409 with code folder_not_empty; when live pending uploads block deletion, error.details.pendingFileIds lists those file ids. Pending uploads past their upload expiry window do not block deletion. Move, cancel, or wait for expiry, then retry.

Auth: API key required.

Operation ID: deleteFolder

Path parameters:

• folderId (string, required)

Responses:

• 200 — The folder was deleted.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan folders delete