Skip to navigation

Reindex document

Reads a document again and indexes it anew, and returns it with status: indexing. A web address is read again from the web; a file is read from the original that was stored when it was uploaded. Use it for a document that failed, or for an address whose page changed. If the stored original is no longer available the answer is 409 source_unavailable and you must upload the file again; a document that cannot be re-indexed gives 400 not_reindexable. With a test key everything is checked but nothing starts: the response has status: simulated. Required scope: knowledge:write. This operation consumes usage (minutes, SMS or model calls) and is billed to the organization. With a test key (vx_test_) it is simulated: nothing real happens and nothing is billed. Requires an Idempotency-Key header. NOT retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the outcome is uncertain and the key becomes “unknown” (the same key gives 409 idempotency_outcome_unknown); with no response at all, the same key returns the first outcome or that same 409. After idempotency_outcome_unknown, read the state of the resource and retry with a new key only if the operation did not happen. A 429 rate_limited from the request limit and 409 request_in_progress come before the operation and leave the key as it is: retry with the same key.

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:
Idempotency-KeystringRequiredformat: "^[A-Za-z0-9_-]{16,64}$"

A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a 4xx error the same request would always get again (not 429, and not the temporary 409 codes request_in_progress, caller_has_active_call and caller_request_in_progress: for those, and for a 5xx, see the note on retrying in the operation); the same key with a different request is refused with idempotency_key_reused.

Response

Accepted: the work continues in the background.

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. simulated: only with a test key, nothing was added or changed.

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.
simulatedboolean

true with a test key: the request was checked and nothing was added or changed.

Errors

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