> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL.

# Folders

`/api/v1` operations for folders. See [HTTP API](/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`

<!-- generated from the /api/v1 OpenAPI spec v1.0.0 (adapter 0.10.0); do not edit by hand -->