Skip to main content
The API authorizes object access but does not proxy private file bytes. It returns short-lived, object-scoped URLs for direct transfer.

​
Upload a knowledge document

1

Create pending metadata

Call createKnowledgeDocument with the file name, byte size, media type, and display name. The response contains the pending document and an upload capability.
2

Upload bytes directly

Send the file to upload.url with the returned HTTP method and every header in upload.headers.
Do not send your Arbol bearer token to the object URL. Use only the headers returned with the capability.
3

Complete ingestion

Before the capability and pending upload expire, call completeKnowledgeDocument for the document ID. Completion validates the object and starts indexing. Completion is idempotent by document ID.
The generated endpoint schema is authoritative for file-size and media-type limits.

​
Download private content

Conversation media, knowledge source bytes, and retained evaluation artifacts use authorization operations that return a short-lived read URL. Fetch that URL without forwarding the Arbol bearer token.
Creating another download capability is safe, but each URL expires. Do not persist it as the durable identifier for an object.

​
Security rules

  • Keep the returned capability URL out of logs and analytics.
  • Never change the method, signed headers, or object key embedded in a capability.
  • Use the API resource ID as the durable reference.
  • Re-authorize immediately before a transfer rather than caching capabilities.