Jelliu API documentation

curl -X POST https://api.jelliu.co/api/agents/7c1e4b2a-9d3f-4e8a-b5c6-2f1a0d9e8b7c/ab-tests \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Variante B — oferta directa",
  "systemPrompt": "Eres Sofía, asesora de Cafés del Huila. Presenta la oferta del plan anual en la primera respuesta.",
  "firstMessage": "Hola, le habla Sofía de Cafés del Huila. Este mes el plan anual tiene dos meses gratis.",
  "weight": 50
}'

{
  "data": {
    "id": "8e7f6a5b-4c3d-4e2f-9a1b-0c9d8e7f6a5b",
    "tenant_id": "2d9f6c1e-3b4a-4c5d-9e8f-7a6b5c4d3e2f",
    "agent_id": "7c1e4b2a-9d3f-4e8a-b5c6-2f1a0d9e8b7c",
    "name": "Variante B — oferta directa",
    "system_prompt": "Eres Sofía, asesora de Cafés del Huila. Presenta la oferta del plan anual en la primera respuesta.",
    "first_message": "Hola, le habla Sofía de Cafés del Huila. Este mes el plan anual tiene dos meses gratis.",
    "weight": 50,
    "is_active": true,
    "total_calls": 0,
    "total_conversions": 0,
    "total_duration_seconds": 0,
    "avg_sentiment": null,
    "created_at": "2026-09-15T14:40:00.000Z",
    "updated_at": "2026-09-15T14:40:00.000Z"
  }
}

Creates a prompt variant for the agent (maximum 10 live variants per agent). When an agent has active variants, each outbound campaign voice call placed by the dialer picks one at random, weighted by weight, and uses its systemPrompt (and firstMessage, when set) in place of the agent’s for that call. Inbound calls, manual calls and text channels always use the agent’s own prompt. Weights are relative: two active variants at 50 and 25 split traffic two to one. A single active variant receives every campaign call.

The call’s outcome, duration and sentiment are added to the variant’s counters when post-call analysis produces an outcome; GET /api/agents/{agentId}/ab-tests/results compares them.

Side effects. Screens the prompt and the first message for fraud (LLM call; a blocked prompt is recorded as a fraud flag). Inserts the variant, which starts affecting the agent’s next campaign dials immediately. Writes an audit entry.

Idempotency. Not idempotent: a retry creates a second variant with the same content and splits traffic further.

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

Access

Required scope: write.
Rate limit: Agent mutations — 10 requests/min per workspace, shared with every agent write; the request is also counted (twice) against the General API limit. See Rate limits.
Plan: A/B testing is gated by plan feature; every plan includes it today.

Creates a prompt variant for the agent (maximum 10 live variants per agent). When an agent has active variants, each **outbound campaign voice call** placed by the dialer picks one at random, weighted by `weight`, and uses its `systemPrompt` (and `firstMessage`, when set) in place of the agent's for that call. Inbound calls, manual calls and text channels always use the agent's own prompt. Weights are relative: two active variants at 50 and 25 split traffic two to one. A single active variant receives every campaign call. The call's outcome, duration and sentiment are added to the variant's counters when post-call analysis produces an outcome; `GET /api/agents/{agentId}/ab-tests/results` compares them. **Side effects.** Screens the prompt and the first message for fraud (LLM call; a blocked prompt is recorded as a fraud flag). Inserts the variant, which starts affecting the agent's next campaign dials immediately. Writes an audit entry. **Idempotency.** Not idempotent: a retry creates a second variant with the same content and splits traffic further. **Webhook events.** `audit.log_recorded` (when subscribed). See [Webhooks](/webhooks). **Access** - **Required scope:** `write`. - **Rate limit:** Agent mutations — 10 requests/min per workspace, shared with every agent write; the request is also counted (twice) against the General API limit. See [Rate limits](/rate-limits). - **Plan:** A/B testing is gated by plan feature; every plan includes it today.

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 the variant belongs to. An unknown id or one from another workspace answers 404; a value that is not a UUID answers 400.

Request

This endpoint expects an object.

namestringRequired1-100 characters

Label shown in results. Trimmed; 1-100 characters after trimming.

systemPromptstringRequired10-8000 characters

The prompt this variant uses instead of the agent’s system_prompt on the calls that pick it. 10-8000 characters, stored as sent (not trimmed). Screened for fraud.

firstMessagestringOptional1-500 characters

Opening line for calls that pick this variant. Trimmed; blank is treated as absent, and then the agent’s first message is used.

weightintegerOptional0-100Defaults to 50

Relative traffic weight, 0-100. Defaults to 50. 0 keeps the variant active but it is never picked while another active variant has weight. Stored as an integer — send whole numbers; a fractional value fails the request.

Response

Variant created (active).

dataobject

A prompt variant row (snake_case), with its raw performance counters.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

The call’s outcome, duration and sentiment are added to the variant’s counters when post-call analysis produces an outcome; GET /api/agents/{agentId}/ab-tests/results compares them.

Idempotency. Not idempotent: a retry creates a second variant with the same content and splits traffic further.

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

Access

Required scope: write.
Rate limit: Agent mutations — 10 requests/min per workspace, shared with every agent write; the request is also counted (twice) against the General API limit. See Rate limits.
Plan: A/B testing is gated by plan feature; every plan includes it today.