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

Observe ingestion

Arbol detects the uploaded object, validates its size and media type, promotes it from pending storage, and indexes it in the background. Poll getKnowledgeDocument with bounded backoff until its index state is ready or reports an error.
The generated endpoint schema is authoritative for file-size and media-type limits.
There is no public “complete upload” endpoint. Completion is internal plumbing: the reconciliation loop makes an uploaded object durable even when the client disconnects after the direct PUT.

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