Upload a knowledge document
Uploads one file as a knowledge source for the agent. Send it as multipart/form-data in a
part named file; the original file name (sanitized, at most 255 characters) becomes the
document name.
Checks run in this order: plan file-count cap, rate limit, then the file itself. The
extension must be one of .pdf, .txt, .docx, .html, .epub, .md, .csv, .json;
the part’s Content-Type must be one of application/pdf, text/plain, text/csv,
text/markdown, text/x-markdown, application/json,
application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/html,
application/epub+zip; and the bytes must match the extension (%PDF- header for PDF, a ZIP
container for DOCX/EPUB, <html or <!DOCTYPE in the first 512 bytes for HTML, no NUL byte
in the first 4 KB for text formats). Text formats (.txt, .csv, .html, .md, .json) are
then screened for prompt-injection and fraud content; PDF, DOCX and EPUB are not screened.
Then the workspace’s total knowledge size is checked with this file included.
By default the call is synchronous and answers 201 once the file is attached to the agent;
indexing continues in the background (status: processing) — poll
GET /api/agents/{agentId}/knowledge for ready. With ?async=true the validated file is
queued and the call answers 202 with a jobId right away; poll
GET /api/agents/{agentId}/knowledge/jobs/{jobId} (kept for 1 hour). In async mode, agent
lookup, provisioning and the size cap are checked by the worker, so those failures appear as
a failed job instead of an HTTP error.
Side effects. Uploads the file to the voice engine and attaches it to the
agent, starts RAG indexing, turns retrieval on for the agent, and extracts the text for the
text channels. If the local save fails (for example the plan cap is hit concurrently), the
provider upload is rolled back. Writes an agent.knowledge.upload audit entry. If the agent
is not yet provisioned, its provisioning job is re-enqueued.
Idempotency. Not idempotent. There is no de-duplication by name or content: retrying after a timeout can attach the same file twice (and count twice against the plan caps). List the documents before retrying.
Webhook events. audit.log_recorded for the audit entry, if you subscribe to it. See Webhooks.
Access
- Required scope:
write. Any workspace role. - Rate limit: Configuration mutations — 10 requests/min per workspace (shared with other agent configuration changes), in addition to the General API limit (120–600/min by plan). See Rate limits.
- Plan: Available on every plan, within the plan’s document caps: Starter 5 files / 10 MB, Growth 25 / 50 MB, Business 100 / 200 MB, Enterprise unlimited size. A workspace without an active plan cannot upload.
Authentication
Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the
dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once,
at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.
Operations restricted to admins or owners reject keys without the full scope with 403, and say so in
their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret —
that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds.
See Authentication.
Path parameters
UUID of the agent. It must belong to the authenticated workspace; an id from another workspace answers 404, exactly like an unknown one. Returned as id by GET /api/agents.
Query parameters
Send true to queue the upload and receive 202 with a job id. Any other value (or
omitting it) processes the upload synchronously and answers 201.
Request
A single file in the multipart part named file. Other parts are ignored; a file under a different part name is not accepted.
The document, at most 20 MB (20971520 bytes). The part’s Content-Type must be one of
the accepted MIME types and its file name must carry an accepted extension.
Response
Uploaded and attached; indexing continues in the background (status = processing).