Files

/api/v1 operations for files. See HTTP 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