Operations
Operations

Generate persona

Generate one or more custom caller personas from a free-text brief. A persona is the SIMULATED CALLER a test scenario runs as, this expands a short brief (e.g. 'impatient elderly caller with hearing loss') into that many full personas, each with a second-person behaviour prompt plus advanced voice settings (accent, speaking pace, interruption level), and saves them to the workspace persona catalogue as 'custom' personas. Use it to quickly populate the catalogue with the kinds of callers you want to test against. Each persona is a TEST HARNESS only, it never changes how the agent itself behaves. Personas are workspace-scoped (reusable across every agent's tests). Persists immediately; call list_personas first so you don't duplicate an existing persona.

POST
/operations/generate_persona

Authorization

bearerAuth
AuthorizationBearer <token>

A personal access token from Settings > API tokens.

In: header

Header Parameters

Idempotency-Key?string

A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/operations/generate_persona" \  -H "Content-Type: application/json" \  -d '{    "brief": "string",    "agent": "string"  }'
{}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}

Export agent spec POST

Return the agent's config as one spec, in exactly the shape apply_agent_spec takes, listing only what differs from a new agent: name, description, systemPrompt, the three greetings, channels, the brief, voice and fallback voice, models, the call engine, speech, turn-taking, behaviour, keyterms, pronunciations, vocabulary, caller memory, guardrails, agent response guardrails, privacy and disclosure settings, call handling, the overflow number, the closed message, answering hours, closed early, caller routing, built-in and HTTP tools with their mocks in the agent's order (not the knowledge-search tool the first knowledge source adds, while it is unchanged), variables (a secret appears as {name, secret: true}; its value is never returned), workflow functions, post-call analysis, knowledge sources (text sources with their text) and test scenarios. Edit it and pass it back to apply_agent_spec with replace: true to make the draft match it. `secrets` says which secret variables hold a value.

Agent health POST

Health check for the agent, answers 'is it live, is it ready, could it improve' in one call. Returns: status (live / published-inactive / draft / archived) and whether an unpublished draft is ahead of the published version; readiness (ready / could-improve / needs-work) with the validator's blocking errors and non-blocking risks (each with section, message, fix link, and, for risks, the riskKey you can pass to acknowledge_risk); reachable (a caller can reach it, a phone number routes here or a channel is enabled) and proven (at least one test's verdict is a pass), surfaced together as qualifiers on a 'ready' label (e.g. 'ready (untested)') since a clean agent that no one can reach or that has never passed a test is not truly ready; a tests summary by each test's latest counted verdict (passed / failed / not-run / inconclusive), where an operator override wins, a passed run whose critical metric failed is a failure, a latest run an operator flagged for review is inconclusive (an older pass does not stand in for it), and an errored, cancelled, unfinished or still-scoring run is inconclusive rather than failed; and recent call activity. Use this first when asked how an agent is doing or whether it's ready to publish.