Agents

An agent is the AI persona that places and answers calls, replies on WhatsApp and email, and chats on your website. It carries everything that decides how a conversation goes: its objective (category), voice and language, the prompt you write, the first thing it says, the channels it may answer on, the post-call analysis it runs, and the tools and conversation graph it can use. Campaigns, phone numbers, widgets and inboxes all point at an agent.

Every agent belongs to one workspace. The API reads and writes the same agents you see under Agents in the dashboard.

How it works

Creating an agent is a two-phase operation. Jelliu validates and screens your request, stores the agent and answers right away; the voice runtime for the agent is then provisioned in the background, which typically takes 30 to 45 seconds. Until that finishes, endpoints that need the runtime answer 409 AGENT_PROVISIONING.

What happens on POST /api/agents, in order:

1. The body is validated. The system prompt, first message and objection handlers are screened for fraud; a blocked prompt fails with 403 COMPLIANCE_BLOCKED before anything is stored.
2. Plan gates run: the agent cap for your plan, cloned voices (Enterprise only), and the dial policy for transferPhoneNumber.
3. The agent is inserted, under a lock that enforces the plan’s agent cap atomically. Version 1 of its history is recorded.
4. The response returns 201 with the stored agent. Provisioning of the voice runtime is queued with up to 3 attempts and exponential backoff.

How the prompt is assembled

The agent’s effective instructions are layered. Jelliu supplies a universal base for the agent’s category, an optional per-objective playbook comes from the linked template (templateId), and your systemPrompt is the part you own. When you change the category, template or prompt, the agent is re-synced to its runtime.

• category is the agent’s objective. It selects the base identity and the default post-call analysis. If you omit it on create, the linked template’s category applies.
• Runtime tuning (turnTimeout, turnEagerness, ttsSpeed, ttsStability, maxCallDurationSeconds) is seeded from the category when you do not send a value, so each objective starts with pacing suited to it.
• Analysis. If you do not send analysis, a default set of success criteria and data-collection fields is generated for the category. Changing the category later regenerates that default analysis, unless the same request also sends analysis.

Categories

Channels

channels lists where the agent may answer: voice, whatsapp, email, webchat, instagram and messenger. An agent created without channels serves all of them.

Object

GET /api/agents and GET /api/agents/{agentId} return agents with the fields below. Timestamps are ISO 8601 strings. Keys are snake_case, except for the three computed flags noted in the table.

GET /api/agents/{agentId} returns every stored column, so it also includes, among others:

Common tasks

Create an agent

curl -sS "https://api.jelliu.co/api/voices" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

curl -sS -X POST "https://api.jelliu.co/api/agents" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Valentina",
    "voiceId": "JBFqnCBsd6RMkjVDRZzb",
    "language": "es-CO",
    "category": "scheduling",
    "channels": ["voice", "whatsapp"],
    "systemPrompt": "Eres Valentina, asistente de la Clínica Dental Sonrisa en Medellín. Ayudas a pacientes a agendar, mover o cancelar citas de valoración.",
    "firstMessage": "Hola, le habla Valentina de la Clínica Dental Sonrisa. ¿En qué le puedo ayudar?",
    "maxCallDurationSeconds": 300,
    "transferPhoneNumber": "+573001234567"
  }'

{
  "data": {
    "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c9f13",
    "tenant_id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
    "name": "Valentina",
    "category": "scheduling",
    "objective": "scheduling",
    "template_id": null,
    "voice_id": "JBFqnCBsd6RMkjVDRZzb",
    "language": "es-CO",
    "channels": ["voice", "whatsapp"],
    "system_prompt": "Eres Valentina, asistente de la Clínica Dental Sonrisa en Medellín. Ayudas a pacientes a agendar, mover o cancelar citas de valoración.",
    "first_message": "Hola, le habla Valentina de la Clínica Dental Sonrisa. ¿En qué le puedo ayudar?",
    "dynamic_variables": {},
    "objection_handlers": {},
    "escalation_rules": [],
    "transfer_rules": [],
    "transfer_phone_number": "+573001234567",
    "max_call_duration_seconds": 300,
    "response_delay_seconds": 0,
    "human_pacing_enabled": true,
    "enable_voicemail_detection": true,
    "disclose_ai": null,
    "department": null,
    "skills": [],
    "expressive_mode": false,
    "tool_call_sound_enabled": false,
    "text_normalisation_type": "elevenlabs",
    "tts_similarity_boost": 0.75,
    "analysis": {
      "successEvaluation": [ { "id": "appointment_booked", "description": "..." } ],
      "dataCollection": [ { "id": "appointment_date", "dataType": "string", "description": "..." } ]
    },
    "safety": null,
    "privacy": { "redactPiiAudio": true, "deleteAudioAfterProcessing": true, "retentionDays": 90 },
    "allowed_toolkits": null,
    "mcpEnabled": true,
    "toolkitAccessEnforced": true,
    "paused_at": null,
    "total_calls": 0,
    "calls_today": 0,
    "conversion_rate": 0,
    "avg_sentiment": null,
    "created_at": "2026-09-15T14:02:11.482Z",
    "updated_at": "2026-09-15T14:02:11.482Z"
  }
}

curl -sS -i "https://api.jelliu.co/api/agents/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c9f13/signed-url" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

Create fields

Asynchronous creation

Add ?async=true to POST /api/agents to run the whole creation, including fraud screening, in the background. The response is 202 Accepted:

{ "data": { "jobId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "status": "pending" } }

Poll GET /api/agents/jobs/{jobId}. data.status moves through pending, processing, then completed (with the agent in data.result) or failed (with the reason in data.error). Job records expire after one hour. The body is still validated synchronously, so an invalid request fails with 400 before a job is created.

List and search agents

GET /api/agents returns up to limit agents (1 to 200, default 50), newest first. Pass the created_at of the last agent as cursor for the next page, and search for a case-insensitive match on the name. See Pagination.

curl -sS "https://api.jelliu.co/api/agents?limit=50&search=valentina" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

{
  "data": [
    {
      "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c9f13",
      "name": "Valentina",
      "category": "scheduling",
      "objective": "scheduling",
      "language": "es-CO",
      "channels": ["voice", "whatsapp"],
      "paused_at": null,
      "tool_surface_status": "synced",
      "created_at": "2026-09-15T14:02:11.482Z",
      "updated_at": "2026-09-15T14:02:11.482Z"
    }
  ]
}

The list response above is abbreviated; each item carries the fields in Object except the detail-only ones. Get one agent with GET /api/agents/{agentId}.

Update an agent

PATCH /api/agents/{agentId} accepts any subset of the create fields, and at least one field must be present. It also accepts fields that exist only on update:

Nullable fields on update: templateId, category, transferPhoneNumber, discloseAi and department accept null to clear them.

curl -sS -X PATCH "https://api.jelliu.co/api/agents/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c9f13" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstMessage": "Hola, gracias por comunicarse con la Clínica Dental Sonrisa. Le habla Valentina.",
    "ttsSpeed": 0.95,
    "analysis": {
      "dataCollection": [
        { "id": "treatment_interest", "dataType": "string", "description": "Tratamiento por el que pregunta el paciente", "enum": ["valoracion", "ortodoncia", "blanqueamiento", "otro"] }
      ]
    }
  }'

The response is 200 with the updated agent in data.

How update merges values:

• analysis, safety, privacy are merged half by half. An absent key keeps what is stored, null clears that half, and a value replaces it. null for the whole block clears it. In the example above, the stored successEvaluation is kept.
• toolkitAccess is merged per app. channels, skills, escalationRules, transferRules, dynamicVariables and objectionHandlers are replaced whole.
• systemPrompt on update must be 10 to 8,000 characters; an empty string is treated as not sent.

Estimate a prompt’s cost

POST /api/agents/prompt-cost measures a draft against the base instructions for its category before you save it. The body is systemPrompt (up to 200,000 characters, so an over-limit draft can still be measured) and optional category.

curl -sS -X POST "https://api.jelliu.co/api/agents/prompt-cost" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "category": "scheduling", "systemPrompt": "Eres Valentina, asistente de la Clínica Dental Sonrisa..." }'

{
  "data": {
    "clientChars": 58,
    "totalChars": 15342,
    "totalTokens": 3836,
    "guidelineTokens": 2000,
    "overGuideline": true,
    "model": "gemini-3.8-flash",
    "usdPerMinute": 0.0071
  }
}

Tokens are estimated at 4 characters per token over the full assembled prompt, and overGuideline flags prompts above 2,000 tokens, where latency and cost start to rise. usdPerMinute is null when the price cannot be fetched.

Pause and resume an agent

Pausing is the emergency stop. A paused agent accepts no new calls or conversation turns; attempts fail with 409 AGENT_PAUSED (or 503 AGENT_PAUSED when the pause state cannot be read, so the stop fails closed). Conversations already in progress continue to their natural end unless you also set terminateActive.

curl -sS -X POST "https://api.jelliu.co/api/agents/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c9f13/pause" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Quoting outdated prices after the catalog change", "terminateActive": true }'

{
  "data": {
    "paused": true,
    "pausedAt": "2026-09-15T16:20:03.114Z",
    "pausedBy": "apikey:6d1f0c2b-4a9e-4f7b-8c3d-2e1a0b9c8d7f",
    "reason": "Quoting outdated prices after the catalog change",
    "termination": {
      "attempted": 3,
      "terminated": 2,
      "stillLiveWithoutCarrierLeg": 1,
      "failed": 0,
      "truncated": false,
      "elapsedMs": 812,
      "slowestCallMs": 431,
      "providerSupportsLiveTermination": false
    },
    "note": "No se aceptan llamadas ni turnos NUEVOS. Se colgaron 2 de 3 llamadas en curso, ..."
  }
}

curl -sS -X DELETE "https://api.jelliu.co/api/agents/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c9f13/pause" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

GET /api/agents/{agentId}/pause returns paused, pausedAt, pausedBy, reason and note without changing anything.

Delete an agent

DELETE /api/agents/{agentId} returns 204 No Content. Deleting:

• pauses every active campaign that uses the agent, so they stop dialing on their next cycle;
• unassigns the agent from its phone numbers, so inbound calls to those numbers need a new agent;
• removes the agent from the voice runtime first, and aborts the delete if that fails, so no orphan is left behind;
• is a soft delete on Jelliu’s side: the version history is kept.

Version history

Every change to an agent’s behavior is recorded as a numbered version: creation, updates, workflow edits, restores and deletion.

A version has id, agent_id, version, change_source (create, update, approved_update, workflow_put, workflow_delete, base_resync, tool_surface, restore, delete), changed_by, actor_type, summary, diff, snapshot_sha256, snapshot_pruned_at, restored_from_version and created_at.

Change approval

A workspace can require a second person to approve behavior changes to agents marked highRisk. It takes both switches: the workspace setting (off by default) and the agent’s highRisk flag.

When both are on, a PATCH that touches a behavior field, a restore, or a workflow change is not applied. The API answers 409 AGENT_CHANGE_PENDING_APPROVAL and returns the request ID:

{
  "error": {
    "code": "AGENT_CHANGE_PENDING_APPROVAL",
    "message": "Este agente está marcado de riesgo alto: el cambio quedó pendiente de que otro usuario lo apruebe.",
    "metadata": {
      "changeRequestId": "c7e1a2b3-4d5f-4a6b-9c8d-7e6f5a4b3c2d",
      "fields": "firstMessage, systemPrompt"
    }
  }
}

Behavior fields are systemPrompt, firstMessage, category, templateId, objectionHandlers, escalationRules, transferRules, transferPhoneNumber, enableVoicemailDetection, safety, privacy, analysis, allowedToolkits, disabledTools, toolkitAccess, mcpEnabled, channels, maxCallDurationSeconds and highRisk itself. Renames, voice, language, pacing and TTS tuning pass straight through.

status is one of pending, approved, rejected, applied, failed, cancelled. approve and reject accept an optional note (up to 2,000 characters). An approved change is re-validated against the current schema and applied; if applying fails, the request ends as failed and must be proposed again.

Tools, workflows and connected apps

These are managed under the agent and are covered in the API reference:

• Tools (/api/agents/{agentId}/tools): webhook tools the agent can call during a conversation, with method, URL, parameters and authentication.
• Workflow (GET, PUT, DELETE /api/agents/{agentId}/workflow): an optional conversation graph of up to 12 nodes and 24 edges. Nodes are subagent steps or end; edges are unconditional, llm (a natural-language condition) or expression (a comparison over up to 6 state variables the agent scores as it goes). Without a workflow the agent runs from its prompt alone.
• Knowledge (/api/agents/{agentId}/knowledge): documents the agent retrieves from. See Knowledge base.
• MCP servers (/api/agents/{agentId}/mcp-servers): external tool servers attached to the agent, allowed only while mcpEnabled is true.
• Controls (/api/agents/{agentId}/controls/limits): tool-call budgets perMinute, perHour, perDay and perConversation. When exhausted, actions fail with 429 AGENT_BUDGET_EXCEEDED. maxSpendPerDayCents is stored but not enforced yet, and the response says so with spendEnforced: false.

Tool and workflow changes need a provisioned agent and answer 409 AGENT_PROVISIONING until then.

Errors

See Errors for the envelope and retry guidance.

Limits

Rate limits. Agent routes are under the general API limit. Mutations (POST /api/agents, PATCH, DELETE, prompt-cost, restoring a version, approving a change request, and tool and workflow writes) also share the 10-per-minute configuration budget with campaigns and webhooks. See Rate limits.

Plan limits. Agents per workspace, including agent add-ons you buy on top:

A workspace without an active plan cannot create agents. Cloned voices are available on Enterprise only.

Scopes.

See Authentication for how scopes map to roles.

Webhooks

See Webhooks for payloads and signature verification.

Related