Documents
Upload, track, replace, download, preview and delete documents.
📄️ List documents; filter by status and change time for bulk status tracking
**Access:** API key scope `knowledge:read` or `knowledge:write`; portal users: any member of the organization; the knowledge base in the path must be on the key's access list.
📄️ Upload 1–50 files (multipart); each file gets its own result
Durable acceptance (`202`), not completion: accepted files continue `uploaded → validating → queued → processing → ready`. Per-file checks (size, extension/MIME/signature, duplicate content, remaining capacity) reject individual files without affecting the others. Request-level failures (authentication, knowledge-base state, too many files, request too large, maintenance, a trial or billing refusal for the whole request) return an error status instead.
📄️ Get a document and its processing status
**Access:** API key scope `knowledge:read` or `knowledge:write`; portal users: any member of the organization; the knowledge base in the path must be on the key's access list.
📄️ Rename and/or replace the whole metadata object
`metadata` replaces the document's metadata entirely (use
📄️ Delete a document (asynchronous; access closes immediately)
**Access:** API key scope `knowledge:write`; portal users: organization admins and owners; the knowledge base in the path must be on the key's access list.
📄️ Replace the document with a new file
Creates a new version of the document. The current ready version stays searchable until the new one is ready, then the switch is atomic. The temporary second copy is not billed as storage; processing the new file is billed. Only one replacement at a time (409 `version_conflict`). Version history is not exposed.
📄️ Download the original file of the visible version (streamed)
Allowed in frozen/suspended states and during payment suspension (download stays open).
📄️ Read-only preview of extracted chunks (visible version), in order
**Access:** API key scope `knowledge:read` or `knowledge:write`; portal users: any member of the organization; the knowledge base in the path must be on the key's access list.
📄️ Retry a failed document or re-attempt admission for one awaiting budget
Allowed when status is `failed` with a retryable failure, or `awaiting_budget`. Otherwise 409 `invalid_document_state`. Platform retries never add a charge.
📄️ Cancel processing of the pending version
Allowed in `uploaded`, `validating`, `queued`, `processing` and `awaiting_budget` (for the first version or a pending replacement). Embedding tokens already produced are billed; unstarted work is free. A document with no ready version ends `cancelled`; with a ready version the pending replacement is dropped and the document stays `ready`.
📄️ Delete up to 100 documents
**Access:** API key scope `knowledge:write`; portal users: organization admins and owners; the knowledge base in the path must be on the key's access list.
📄️ Set and/or unset metadata keys on up to 100 documents
Applied per document; a document that would exceed 16 keys fails individually with `metadata_too_many_keys`. `set` and `unset` must not share a key.