> 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. # Files `/api/v1` operations for files. See [HTTP API](/api/) for authentication, the error envelope, and rate limits. ## Operations ### GET /api/v1/files List files Returns the organization's non-deleted files ordered newest first, with cursor pagination (default 50 per page, max 200). By default only ready files appear; pass status=pending to list incomplete uploads that have not passed their upload expiry window (cancel them with DELETE /api/v1/files/{fileId}). Scope the list with folderId or path (mutually exclusive); path=/ means the root folder, and omitting both lists every folder. Each file includes contentUrl, a stable authenticated API URL for opening the file content. Auth: API key required. Operation ID: `listFiles` Query parameters: - `folderId` (string, optional) - `path` (string, optional) - `status` ("ready" | "pending", optional) - `limit` (integer, optional) - `cursor` (string, optional) Responses: - `200` — One page of the organization's files. - `400` — The request was malformed or failed validation. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan files list` ### POST /api/v1/files/uploads Prepare file uploads Validates up to 10 files (1GB each), persists pending records, and returns a presigned PUT URL, required headers, and an expiry per file. PUT each file's bytes to its uploadUrl with the returned headers, then call the complete endpoint with the file ids. Target a folder with folderId or folderPath (mutually exclusive); folderPath creates missing folders along the way. Pending uploads that are never completed expire and are cleaned up automatically. Auth: API key required. Operation ID: `prepareFileUploads` Request body (`application/json`, required): - `files` (object[], required) — Up to 10 files, 1GB each, per request. - `folderId` (string | null, optional) - `folderPath` (string | null, optional) — Target folder path; missing folders are created ("mkdir -p" semantics). Responses: - `200` — Per-file presigned upload instructions. - `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. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan files uploads prepare` ### POST /api/v1/files/uploads/complete Complete file uploads Verifies each prepared upload (object presence and size) and promotes verified files to ready. Returns a per-file ready or failed result instead of failing the whole batch; failed entries carry an error message (e.g. an expired upload window). Completing an already-completed batch is idempotent. Auth: API key required. Operation ID: `completeFileUploads` Request body (`application/json`, required): - `files` (object[], required) Responses: - `200` — Per-file completion results. - `400` — The request was malformed or failed validation. - `401` — Authentication is missing or invalid. - `403` — The caller is not permitted to perform this action. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan files uploads complete` ### GET /api/v1/files/{fileId} Get a file Returns the file's record, including its folder id, resolved path, and stable authenticated contentUrl. Pending (prepared but not yet completed) files are visible here with status pending; deleted files respond 404. Auth: API key required. Operation ID: `getFile` Path parameters: - `fileId` (string, required) Responses: - `200` — The file record. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan files get` ### PATCH /api/v1/files/{fileId} Rename or move a file Renames the file (name) and/or moves it (folderId or folderPath, mutually exclusive; null folderId or path / targets the root). When both a rename and a move are requested they apply in sequence — rename, then move — and a move failure leaves the rename applied. A folderPath creates any missing folders along the path (mkdir -p), matching upload prepare. Auth: API key required. Operation ID: `updateFile` Path parameters: - `fileId` (string, required) Request body (`application/json`, required): - `name` (string, optional) - `folderId` (string | null, optional) — Destination folder id; null moves the file to the root. - `folderPath` (string, optional) — Destination folder path; "/" moves the file to the root. Missing folders along the path are created ("mkdir -p" semantics), matching upload prepare. Responses: - `200` — The updated file record. - `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 files update` ### DELETE /api/v1/files/{fileId} Delete a file Soft-deletes the file and removes its bytes from storage. Works for ready files and pending uploads (cancel an incomplete upload by deleting it). The file disappears from listings immediately; deletion is permanent. Auth: API key required. Operation ID: `deleteFile` Path parameters: - `fileId` (string, required) Responses: - `200` — The file was deleted. - `401` — Authentication is missing or invalid. - `403` — The caller is not permitted to perform this action. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan files delete` ### GET /api/v1/files/{fileId}/content Open file content Authenticates the caller, verifies the file belongs to the caller's organization and is ready, then redirects to a short-lived inline storage URL. File records expose this path as contentUrl; send the same API key when requesting it. Auth: API key required. Operation ID: `openFileContent` Path parameters: - `fileId` (string, required) Responses: - `302` — Redirects to the short-lived inline storage URL. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `409` — Response. - `429` — Too many requests; retry after the indicated delay. ### GET /api/v1/files/{fileId}/download Get a download URL Returns a short-lived presigned URL (attachment disposition) for a ready file; fetch the bytes directly from that URL before it expires. The URL grants access to the file contents — treat it as a secret and request a fresh one per download. Responds 409 until the file is ready. Auth: API key required. Operation ID: `getFileDownloadUrl` Path parameters: - `fileId` (string, required) Responses: - `200` — The presigned download URL and its expiry. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `409` — Response. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan files download-url` ### GET /api/v1/files/{fileId}/preview Get a preview URL Returns a short-lived presigned URL (inline disposition) for a ready, preview-eligible file (images and PDFs); load the bytes directly from that URL before it expires. The URL grants access to the file contents — treat it as a secret and request a fresh one per render. Responds 409 until the file is ready, and 415 when the file cannot be previewed inline. Auth: API key required. Operation ID: `getFilePreviewUrl` Path parameters: - `fileId` (string, required) Responses: - `200` — The presigned preview URL and its expiry. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `409` — Response. - `415` — Response. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan files preview-url`