Skip to navigation

Get document

Returns one document with its indexing status. Poll it after adding or re-indexing a document: status goes from pending to indexing and then to ready or failed. When it is failed, failure.code is indexing_failed: the internal reason is not exposed, and POST /knowledge/documents/{document_id}/reindex tries again. A document with needs_review: true is not used by the agents until a person approves it in the app. Required scope: knowledge:read. With a test key (vx_test_) it behaves exactly as with a live key and consumes nothing.

Authentication

AuthorizationBearer
API key created by an Owner or Admin of the organization. Never in the query string.

Path parameters

document_idstringRequiredformat: "uuid"

Id of the document, as returned by GET /knowledge/documents or when it was added.

Headers

VoxAI-VersionenumOptional

API version for this request; defaults to the version the key is pinned to.

Allowed values:

Response

Successful response.
object"knowledge_document"

Always knowledge_document.

idstring

Id of the document: use it in GET /knowledge/documents/{document_id} and in the other document operations.

namestring

The name shown for the document: the name given when it was added, or else the file name or the address.

typeenum

file: a file that was uploaded. url: a web address that was read.

Allowed values:
source_urlstring or null

The web address the document was read from; null for a file.

statusenum

pending: registered, indexing not started yet. indexing: being read and indexed. ready: indexed, the agents can answer from it. failed: indexing failed, see failure.

Allowed values:
failureobject or null

Set when status is failed. The internal reason is not exposed.

chunk_countinteger>=0
Number of searchable passages the document was split into.
indexed_atdatetime or null

When the document was indexed, ISO 8601 UTC; null if it was not indexed.

needs_reviewboolean

true when a person must review the text read from the document in the app: until it is approved the agents do not use it and POST /knowledge/search does not return it.

reviewed_atdatetime or null

When a person approved the document after review, ISO 8601 UTC; null if it was not reviewed.

created_atdatetime or null
When the document was added, ISO 8601 UTC.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error