Jelliu API documentation

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.

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](/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](/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

AuthorizationBearer

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.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

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.

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. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | 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](/authentication).

Path parameters

agentIdstringRequiredformat: "uuid"

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

asyncenumOptional

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.

Allowed values:

Request

A single file in the multipart part named file. Other parts are ignored; a file under a different part name is not accepted.

filefileRequired

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

dataobject

A document in an agent's knowledge base. The extracted text and provider ids are never returned.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error

502

Bad Gateway Error

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.

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.