Documents API
Documents are read and edited under /api/v1/documents. Content is brought in
under /api/v1/ingest, which records a run you follow through the
Ingestion runs API.
The document object
DocumentResponse. Every field is read from the stored document.
| Property | Type | Description |
|---|---|---|
id | string | Document id |
title | string | Title |
filename | string | null | Original file name, for uploads |
source_url | string | null | Address at the source |
metadata | object | Stored metadata, including source_id |
created_at, updated_at | datetime | Timestamps |
chunk_count | integer | null | Number of chunks |
embedded_chunk_count | integer | null | Chunks with a vector in the active embedding space (detail responses only) |
collection_id, project_id, org_id | string | null | Where it belongs |
file_type | string | null | Stored file type |
size_bytes | integer | null | Stored size |
status | string | pending, processing, indexed or failed. Only indexed documents are used in answers |
source_type | string | null | upload, manual, api, or the connector type that brought it in |
connector_id | string | null | Connector that brought it in |
restricted | boolean | Access is limited to the people the source shares it with |
permissions_confirmed_at | datetime | null | When mirrored sharing was last confirmed |
Document records
POST /api/v1/documents/
Create a document record without chunking or embeddings. To make content
searchable, use POST /api/v1/ingest/document instead. Returns 201 with a
document object.
| Property | Type | Required | Description |
|---|---|---|---|
title | string | * | Document title |
content | string | * | Document content |
source_url | string | Source URL | |
metadata | object | Additional metadata | |
collection_id | string | Collection ID | |
org_id | string | Must match the caller's organization when sent |
GET /api/v1/documents/
List documents the caller may read, with pagination.
| Query | Type | Description |
|---|---|---|
search | string | Search term for title or content |
project_id | uuid | Documents this project can read |
collection_id | uuid | One collection |
status | string | pending, processing, indexed or failed |
connector_id | string | Only documents this connector brought in |
added_by_hand | boolean | Only uploaded or pasted documents |
no_collection | boolean | Only documents in no collection |
Response (PaginatedResponse): items (document objects), total, page,
page_size, total_pages.
GET /api/v1/documents/lookup
Trace one document from its source to an answer. Organization admins only: the trace says that a document exists whoever may read it. Nothing is changed.
| Query | Type | Required | Description |
|---|---|---|---|
q | string | * | A document id, its source address or source id, or part of its title (2+ characters) |
user_email | string | Check access for this person. Without it, access is checked for public channels | |
project_id | uuid | Check that this project can read the document's source |
Response:
| Property | Description |
|---|---|
found | Whether a document matched |
verdict | {ok, check, message}. check is the key of the first failing check, or null |
checks | Ordered list of {key, label, ok, detail}. ok is true, false or null. null is a caution: the document is usable, with a limit described in detail. A caution does not make the verdict fail |
last_attempt | When nothing matched: the latest failed or skipped run item for it (title, source_ref, stage, outcome, reason_code, detail, created_at, run_id), or null |
document | {id, title, source_url, status, collection_id, collection_name, connector_id, source_type, chunk_count, embedded_chunk_count, restricted} or null |
matches | Other matching documents (id, title, source_url) |
chunks | The first three chunks (ord, tokens, chunking_strategy, text) |
Check keys, in order:
| Key | Passes when |
|---|---|
found | A document matches |
indexed | Status is indexed and it has chunks |
embedded | Every chunk has a vector in the active embedding space. null when the document has chunks but some lack a vector: it is found by keyword only until its embeddings are repaired |
project | Only with project_id: the project owns the source or has it connected |
permissions | Only for restricted documents: sharing was confirmed within the validity window (ACL_MAX_STALENESS_HOURS, default 24) |
person | The named person, or a public channel, can read it |
GET /api/v1/documents/{doc_id}
One document object, with chunk_count and embedded_chunk_count. Optional
query project_id: the consuming project whose source binding authorizes the
read. 400 for a malformed id, 404 when it does not exist or the caller may
not read it.
PUT /api/v1/documents/{doc_id}
Update a document. All fields are optional: title, content, source_url,
metadata, collection_id (moves the document to that collection). Returns
the document object.
DELETE /api/v1/documents/{doc_id}
Delete a document and its chunks. Returns 204.
GET /api/v1/documents/{doc_id}/chunks
A list of chunks: id, doc_id, text, ord, tokens, chunking_strategy,
created_at. Optional query project_id, as for the document itself.
Ingest
Both ingest endpoints check the request, record a run and return 202 at once.
Processing happens in the background.
{
"run_id": "<run-id>",
"status": "queued",
"status_url": "/api/v1/ingestion/runs/<run-id>",
"message": "Ingestion accepted; poll status_url for progress and the resulting document."
}Poll status_url. When the run is completed, run.detail.document_id is the
new document.
Checks made before 202:
| Status | When |
|---|---|
400 | Unknown chunking_strategy |
402 | Not enough credits (detail.error = "insufficient_credits") |
403 | The caller may not write to that collection |
413 | Upload larger than INGESTION_MAX_UPLOAD_MB (default 100); detail.error = "file_too_large", detail.limit_mb |
429 | Plan limit reached (detail.error is document_limit_reached or storage_limit_reached) |
503 | No rate is configured for ingestion (detail.code = "billing_catalogue_unconfigured"). A fresh install returns this until an operator applies the billing catalogue |
Plan limits are measured from stored documents, so connector-synced documents count and deleting documents frees room. Credits are deducted only after a run completes; a failed run is not charged.
POST /api/v1/ingest/document
Ingest pasted text. JSON body:
| Property | Type | Required | Description |
|---|---|---|---|
title | string | * | Document title |
content | string | * | Document content |
source_url | string | Source URL | |
metadata | object | Additional metadata | |
collection_id | string | Target collection | |
org_id | string | Must match the caller's organization when sent |
Query: generate_embeddings (boolean, default true) and chunking_strategy
(WORD_BASED, SEMANTIC, MARKDOWN or CODE; default WORD_BASED).
POST /api/v1/ingest/upload
Upload one file as multipart/form-data.
| Field | Type | Required | Description |
|---|---|---|---|
file | file | * | The file to ingest |
collection_id | string | Target collection | |
title | string | Defaults to the file name | |
source_id | string | A stable id that makes the document updatable: uploading the same id with changed content replaces it | |
generate_embeddings | boolean | Default true |
The file is staged until its run completes. After a failure it is kept for
INGESTION_FAILED_INPUT_RETENTION_HOURS (default 24) so the run can be
retried without uploading again. A file
that cannot be read fails its run with a reason code; it is not a 4xx on this
request.
POST /api/v1/ingest/{doc_id}/reprocess
Chunk an existing document again and re-embed it. Runs inline and returns 200.
Query: generate_embeddings (default true) and chunking_strategy. The
document is not used in answers while this runs. The work is recorded as a
reprocess run.
{"run_id": "...", "document_id": "...", "title": "...", "chunk_count": 12, "embedded_chunks": 12}400 when the document has no content. On failure the response is 500 with
detail.error, detail.message and detail.run_id.
POST /api/v1/ingest/{doc_id}/embeddings
Embed a document's existing chunks again, for example after embedding_pending.
Same response as reprocess. 400 when the document has no chunks.
Images
GET /api/v1/multimodal/documents/{doc_id}/images
Images extracted from a document, with metadata.