Skip to navigation
API ReferenceAgents

Create an A/B variant

View as Markdown

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 also counts against the General API limit. See Rate limits.
  • Plan: Every plan includes A/B testing. It requires an active subscription (active, trialing or past_due); without one every A/B test operation, reads included, is refused with 403 BILLING_ERROR (metadata.kind: subscription_required).

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.

ScopeGET / HEADPOST / PUT / PATCH / DELETEAdmin-only routes
readYesNoNo
writeYesYesNo
fullYesYesYes

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

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