Pragence

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.

PropertyTypeDescription
idstringDocument id
titlestringTitle
filenamestring | nullOriginal file name, for uploads
source_urlstring | nullAddress at the source
metadataobjectStored metadata, including source_id
created_at, updated_atdatetimeTimestamps
chunk_countinteger | nullNumber of chunks
embedded_chunk_countinteger | nullChunks with a vector in the active embedding space (detail responses only)
collection_id, project_id, org_idstring | nullWhere it belongs
file_typestring | nullStored file type
size_bytesinteger | nullStored size
statusstringpending, processing, indexed or failed. Only indexed documents are used in answers
source_typestring | nullupload, manual, api, or the connector type that brought it in
connector_idstring | nullConnector that brought it in
restrictedbooleanAccess is limited to the people the source shares it with
permissions_confirmed_atdatetime | nullWhen 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.

PropertyTypeRequiredDescription
titlestring*Document title
contentstring*Document content
source_urlstringSource URL
metadataobjectAdditional metadata
collection_idstringCollection ID
org_idstringMust match the caller's organization when sent

GET /api/v1/documents/

List documents the caller may read, with pagination.

QueryTypeDescription
searchstringSearch term for title or content
project_iduuidDocuments this project can read
collection_iduuidOne collection
statusstringpending, processing, indexed or failed
connector_idstringOnly documents this connector brought in
added_by_handbooleanOnly uploaded or pasted documents
no_collectionbooleanOnly 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.

QueryTypeRequiredDescription
qstring*A document id, its source address or source id, or part of its title (2+ characters)
user_emailstringCheck access for this person. Without it, access is checked for public channels
project_iduuidCheck that this project can read the document's source

Response:

PropertyDescription
foundWhether a document matched
verdict{ok, check, message}. check is the key of the first failing check, or null
checksOrdered 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_attemptWhen 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
matchesOther matching documents (id, title, source_url)
chunksThe first three chunks (ord, tokens, chunking_strategy, text)

Check keys, in order:

KeyPasses when
foundA document matches
indexedStatus is indexed and it has chunks
embeddedEvery 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
projectOnly with project_id: the project owns the source or has it connected
permissionsOnly for restricted documents: sharing was confirmed within the validity window (ACL_MAX_STALENESS_HOURS, default 24)
personThe 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:

StatusWhen
400Unknown chunking_strategy
402Not enough credits (detail.error = "insufficient_credits")
403The caller may not write to that collection
413Upload larger than INGESTION_MAX_UPLOAD_MB (default 100); detail.error = "file_too_large", detail.limit_mb
429Plan limit reached (detail.error is document_limit_reached or storage_limit_reached)
503No 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:

PropertyTypeRequiredDescription
titlestring*Document title
contentstring*Document content
source_urlstringSource URL
metadataobjectAdditional metadata
collection_idstringTarget collection
org_idstringMust 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.

FieldTypeRequiredDescription
filefile*The file to ingest
collection_idstringTarget collection
titlestringDefaults to the file name
source_idstringA stable id that makes the document updatable: uploading the same id with changed content replaces it
generate_embeddingsbooleanDefault 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.

On this page