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
Headers
API version for this request; defaults to the version the key is pinned to.
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
An http(s) address: the page and the pages it links to are indexed.
The name shown for the document (default: the file name or the address).
Computed by the server for uploaded files; ignored if sent.
Response
Accepted: the work continues in the background.
Always knowledge_document.
Id of the document: use it in GET /knowledge/documents/{document_id} and in the other document operations.
The name shown for the document: the name given when it was added, or else the file name or the address.
file: a file that was uploaded. url: a web address that was read.
The web address the document was read from; null for a file.
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.
Set when status is failed. The internal reason is not exposed.
When the document was indexed, ISO 8601 UTC; null if it was not indexed.
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.
When a person approved the document after review, ISO 8601 UTC; null if it was not reviewed.
true with a test key: the request was checked and nothing was added or changed.