Skip to navigation

Create document

Adds a document to the knowledge base from a web address or from a file, and returns it with status: pending: indexing runs in the background, so the agents can use the document only when status is ready. Send a JSON body with url (an http or https address, without user name or password), or multipart/form-data with file (PDF, text, .docx, .xlsx, HTML, Markdown, CSV, RTF or JSON, up to 20 MB) and an optional name; never both. A file with the same content as an existing one gives 409 duplicate_content, the same name with different content 409 name_conflict, and an identical file or an address already added 409 already_exists. If the storage of the organization is full the answer is 422 knowledge_storage_full. The knowledge base must be included in the plan. With a test key everything is checked but nothing is added: 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. Retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the key is released and a retry with the same key runs the operation again; with no response at all, a retry with the same key returns the first outcome or runs the operation again. 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.

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.

Request

This endpoint expects an object.
urlstringOptional<=2000 characters

An http(s) address: the page and the pages it links to are indexed.

namestringOptional1-200 characters

The name shown for the document (default: the file name or the address).

file_sha256stringOptional

Computed by the server for uploaded files; ignored if sent.

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
409
Conflict Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error