Jelliu API documentation

Creates an agent. The row is stored immediately and returned with 201 in about 1-2 seconds; provisioning with the voice engine continues in the background for about 30-45 seconds. Meanwhile operations that need the provider (GET /api/agents/{agentId}/signed-url, tools, workflow, knowledge, MCP servers) answer 409 AGENT_PROVISIONING with Retry-After: 5. Edits sent with PATCH /api/agents/{agentId} during that window are picked up by provisioning.

Only name, voiceId and language are required. Runtime tuning you omit is seeded from the objective (category), and when analysis is omitted a default set of success criteria and extraction fields for that objective is stored. When firstMessage is empty a greeting is built from the agent name and the workspace’s business name.

Checks run in this order, and the first failure answers: role and plan agent cap, body validation, workspace still exists, reserved qa_ criterion ids, fraud screening of the prompt, first message and objection handlers, cloned-voice plan check, dial policy for transferPhoneNumber, template access, and a final atomic agent-cap check at insert time.

With ?async=true only the role, plan cap and body validation run in the request; the call answers 202 with a job id and everything else runs in a worker. Poll GET /api/agents/jobs/{jobId} (kept for one hour) for the result or the error.

Side effects. Calls an LLM to screen the prompt for fraud (a blocked prompt is recorded as a fraud flag on the workspace). Inserts the agent and version 1 of its change history, then enqueues the voice-engine provisioning job, which creates the voice agent and attaches the post-call webhook, tools and MCP gateway. Writes an audit entry. An in-app notification is posted when provisioning finishes or fails.

Idempotency. Not idempotent. Retrying after a timeout creates a second agent (and a second voice agent) and consumes another slot of the plan’s agent cap. Check GET /api/agents?search= before retrying.

Webhook events. audit.log_recorded (when subscribed). See Webhooks.

Access

Required scope: write. Signed-in users need the owner, admin or member role; viewers get 403 Insufficient permissions.
Rate limit: Agent mutations — 10 requests/min per workspace, shared with every agent, A/B variant, tool and knowledge write; the request also counts against the General API limit. See Rate limits.
Plan: Agent cap by plan — Starter 2, Growth 5, Business 12, Enterprise unlimited, plus purchased agent add-ons; a workspace without an active plan or trial cannot create agents. Custom cloned voices require Enterprise.

Creates an agent. The row is stored immediately and returned with `201` in about 1-2 seconds; provisioning with the voice engine continues in the background for about 30-45 seconds. Meanwhile operations that need the provider (`GET /api/agents/{agentId}/signed-url`, tools, workflow, knowledge, MCP servers) answer `409 AGENT_PROVISIONING` with `Retry-After: 5`. Edits sent with `PATCH /api/agents/{agentId}` during that window are picked up by provisioning. Only `name`, `voiceId` and `language` are required. Runtime tuning you omit is seeded from the objective (`category`), and when `analysis` is omitted a default set of success criteria and extraction fields for that objective is stored. When `firstMessage` is empty a greeting is built from the agent name and the workspace's business name. Checks run in this order, and the first failure answers: role and plan agent cap, body validation, workspace still exists, reserved `qa_` criterion ids, fraud screening of the prompt, first message and objection handlers, cloned-voice plan check, dial policy for `transferPhoneNumber`, template access, and a final atomic agent-cap check at insert time. With `?async=true` only the role, plan cap and body validation run in the request; the call answers `202` with a job id and everything else runs in a worker. Poll `GET /api/agents/jobs/{jobId}` (kept for one hour) for the result or the error. **Side effects.** Calls an LLM to screen the prompt for fraud (a blocked prompt is recorded as a fraud flag on the workspace). Inserts the agent and version 1 of its change history, then enqueues the voice-engine provisioning job, which creates the voice agent and attaches the post-call webhook, tools and MCP gateway. Writes an audit entry. An in-app notification is posted when provisioning finishes or fails. **Idempotency.** Not idempotent. Retrying after a timeout creates a second agent (and a second voice agent) and consumes another slot of the plan's agent cap. Check `GET /api/agents?search=` before retrying. **Webhook events.** `audit.log_recorded` (when subscribed). See [Webhooks](/webhooks). **Access** - **Required scope:** `write`. Signed-in users need the owner, admin or member role; viewers get `403 Insufficient permissions`. - **Rate limit:** Agent mutations — 10 requests/min per workspace, shared with every agent, A/B variant, tool and knowledge write; the request also counts against the General API limit. See [Rate limits](/rate-limits). - **Plan:** Agent cap by plan — Starter 2, Growth 5, Business 12, Enterprise unlimited, plus purchased agent add-ons; a workspace without an active plan or trial cannot create agents. Custom cloned voices require Enterprise.

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

Query parameters

asyncstringOptional

Send true to queue the creation and receive a job id (202) instead of the agent. Only the literal string true is recognised; any other value (1, yes) is ignored and the creation runs synchronously.

Request

This endpoint expects an object.

namestringRequired1-100 characters

Display name of the agent, also used in the generated greeting. 1-100 characters.

voiceIdstringRequired>=1 character

Voice id (see the voices endpoints). A custom cloned voice requires the Enterprise plan (403 BILLING_ERROR otherwise).

languageenumRequired

Main language of the agent: es (Spanish), es-CO (Colombia), es-MX (Mexico), es-AR (Argentina), es-neutral (neutral Latin American Spanish), en, en-US, pt, pt-BR. Common labels are also accepted case-insensitively and normalised (for example Español (LATAM) → es-neutral, Portuguese → pt, México → es-MX); anything else is rejected with 400.

channelslist of enumsOptional

Channels the agent may answer on. Omitted = every channel. At least one. The list is stored as sent and later edits replace it — it is never a delta.

templateIdstringOptionalformat: "uuid"

Objective template (per-objective playbook layered under the workspace prompt). Must be a system template or one owned by the workspace; otherwise 400.

categoryenumOptional

The agent’s objective. It selects the base agent, default tuning and default analysis, and wins over the template’s category. Omit to inherit the template’s category. Values: sales, support, scheduling, surveys, collections, retention, notifications, interview (candidate screening), language_assessment (scored spoken evaluation), personal (personal assistant), general.

systemPromptstringOptional<=8000 charactersDefaults to

The workspace’s own prompt layer, placed on top of the platform and objective layers. Trimmed. Must be empty (the agent introduces itself generically and never invents a product) or 10-8000 characters. Screened for fraud. Catalogues and price lists belong in the knowledge base.

firstMessagestringOptional<=500 charactersDefaults to

Opening line. Trimmed. When empty a greeting is generated from the agent name and the workspace’s business name (for example Hola, le habla Sofía de Cafés del Huila. ¿Cómo está?). Screened for fraud.

dynamicVariablesmap from strings to stringsOptionalDefaults to {}

Key/value strings stored with the agent (at most 50 entries; keys up to 100 characters, values up to 500). Stored and versioned; not currently applied to conversations.

objectionHandlersmap from strings to stringsOptionalDefaults to {}

Objection → suggested answer (at most 50 entries; keys up to 100 characters, values up to 2000). Each value is screened for fraud. Stored and versioned; not currently applied to conversations — put objection guidance in systemPrompt.

escalationRuleslist of objectsOptionalDefaults to []

Escalation rules. Stored and versioned; not currently applied to conversations — escalation to a human is handled by the platform’s own escalation tool.

maxCallDurationSecondsdoubleOptional30-3600

Hard cap on a voice call, in seconds (30-3600). Omitted = the objective’s cap. The objective’s cap also acts as a ceiling when the provider configuration is derived.

transferPhoneNumberstringOptionalformat: "^\+[1-9]\d{1,14}$"

E.164 number the voice agent may transfer live calls to. The destination must be allowed by the workspace dial policy (403 COMPLIANCE_BLOCKED otherwise).

discloseAiboolean or nullOptional

Whether the agent opens by saying it is an AI. true/false is this agent’s decision and overrides the country policy; omitted or null lets the country policy decide.

enableVoicemailDetectionbooleanOptionalDefaults to true

Detect voicemail on outbound calls and hang up instead of talking to the machine.

transferRuleslist of objectsOptionalDefaults to []

In-call hand-offs to other agents of the workspace (up to 10). Targets that do not exist or are not provisioned yet are skipped silently when the provider configuration is built.

departmentstringOptional1-100 characters

Department used by inbound skill-based routing. Trimmed; blank is treated as absent.

skillslist of stringsOptionalDefaults to []

Skills matched by inbound skill-based routing (up to 50, each trimmed, 1-100 characters).

safetyobjectOptional

Guardrails — topics the agent refuses to discuss. Pushed to the voice provider’s guardrails.

privacyobjectOptional

PII redaction and data retention. On create the defaults below are stored even when the block is omitted; on update nothing is defaulted.

analysisobjectOptional

Post-call analysis run by the voice provider on the transcript. successEvaluation criteria decide whether a conversation succeeded (they drive outcomes and conversion metrics); dataCollection fields are extracted from the transcript. Criterion ids starting with qa_ are reserved for platform quality evaluation and a NEW one is rejected with 400 (ids already stored keep saving).

expressiveModebooleanOptionalDefaults to false

Lets the voice model use expressive delivery (audio tags such as laughter or emphasis).

toolCallSoundEnabledbooleanOptionalDefaults to false

Play a short sound on voice calls while a tool is running.

textNormalisationTypeenumOptionalDefaults to elevenlabs

How numbers, dates and symbols are turned into speakable text: elevenlabs (the provider normalises before speech) or system_prompt (the model is instructed to write them out).

turnTimeoutdoubleOptional1-10

Voice only — seconds of silence before the agent takes the turn (1-10). Omitted = the objective’s value.

turnEagernessenumOptional

How eagerly the voice agent takes the turn: patient, normal, eager. The legacy spellings low, medium and high are still accepted. Omitted = the objective’s value.

ttsSpeeddoubleOptional0.5-2

Speech rate, 0.5-2 (1 = the voice’s natural speed). Omitted = the objective’s value.

ttsStabilitydoubleOptional0-1

Voice stability, 0-1. Lower is more expressive, higher more consistent. Omitted = the objective’s value.

ttsSimilarityBoostdoubleOptional0-1Defaults to 0.75

How closely synthesis adheres to the original voice, 0-1.

Response

Agent created. It is still being provisioned with the voice provider.

dataobject

An agent as returned by GET /api/agents, GET /api/agents/{agentId} and POST /api/agents. Stored columns are snake_case (see AgentRowBase); the fields the API adds on top of them (channels, objective, analysis, safety, privacy, mcpEnabled, toolkitAccessEnforced, total_calls, conversion_rate, calls_today, avg_sentiment) are listed below, and the raw JSON columns they come from (supported_channels, analysis_config, safety_config, privacy_config) are not returned. analysis, safety and privacy are omitted when nothing is stored. GET /api/agents returns a projection (see that operation). The provider’s internal voice agent id is never returned.

A newly created agent is provisioned with the voice provider in the background for about 30-45 seconds; operations that need it answer 409 AGENT_PROVISIONING meanwhile.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

Webhook events. audit.log_recorded (when subscribed). See Webhooks.

Access

Required scope: write. Signed-in users need the owner, admin or member role; viewers get 403 Insufficient permissions.
Rate limit: Agent mutations — 10 requests/min per workspace, shared with every agent, A/B variant, tool and knowledge write; the request also counts against the General API limit. See Rate limits.
Plan: Agent cap by plan — Starter 2, Growth 5, Business 12, Enterprise unlimited, plus purchased agent add-ons; a workspace without an active plan or trial cannot create agents. Custom cloned voices require Enterprise.