Agents
Agents

Send the agent a text message and get its reply

Have a live text conversation with the agent, the headless equivalent of the Test panel. Send a `message`, get back the agent's `reply`, the `toolCalls` it ran, and turn `timing`. Multi-turn: pass the returned `conversationId` back to keep the same thread (the agent remembers prior turns and won't re-fire tools it already ran). Defaults to the latest draft so edits you just made are testable immediately, use this to iterate: edit the agent, talk to it, see how it responds, refine. Each turn runs the real agent loop (executing tools) and is billed like a Test-panel turn; the conversation shows up in the Transcripts dashboard.

POST
/workspaces/{workspace}/agents/{agent}/conversations

Authorization

bearerAuth
AuthorizationBearer <token>

A personal access token from Settings > API tokens.

In: header

Path Parameters

workspace*string

Workspace slug (GET /me lists yours).

agent*string

Agent slug within the workspace.

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/workspaces/string/agents/string/conversations" \  -H "Content-Type: application/json" \  -d '{    "message": "string"  }'
{
  "reply": "string",
  "conversationId": "string",
  "property1": null,
  "property2": null
}
{
  "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
}

Restore an archived agent POST

Restore an archived agent, clears `archived_at` so it reappears in the workspace agents list. The reverse of `archive_agent`. No-op (still succeeds) if the agent isn't archived.

Update an agent from a partial spec PATCH

Make the agent's draft match a spec in one call. The spec is what export_agent_spec returns: export, edit, apply. Each field is written by the op named here, which checks it: name, description, systemPrompt (update_system_prompt), greeting, returningGreeting, outboundGreeting, channels (set_agent_channels), brief (set_brief), voice, fallbackVoice, model, fallbackModel, sttModel, judgeModel, callEngine (set_realtime), speech (set_speech_settings), turnTaking (set_turn_detection), behaviour (set_behaviour_settings), keyterms, pronunciations, vocabulary, callerMemory, guardrails (set_safety_guardrails), agentResponseGuardrails (set_agent_response_guardrails), settings (update_agent_settings: disclosures, privacy, retention, timezone), callHandling, overflowForwardNumber, closedMessage, answeringHours, closedEarly (set_manual_close), callerRouting (set_caller_routing). Lists match by name: builtinTools, httpTools (add the tool, then the set_tool_* ops), toolOrder (reorder_tools), variables ({name, value}; {name, default} for a value injected per call; {name, secret: true}, set with set_secret_variable), workflow {preCall, callEnded, postCall}, postCallAnalysis {summary, fields}, knowledge ({name, text}, {name, url}, or {name, file: true}, uploaded in the app), scenarios (create_scenario inputs). An omitted field is left as it is; null resets it to the default. replace: true makes the spec the whole config: a key left out of an object field is reset, and a list item left out is deleted, except that knowledge-search tool, which stays while the agent has knowledge. Only what differs is written, and every step is checked before the first write. Deletes run last. If a step fails, every step before it is undone and the error names the step. If the latest version is published, a draft is opened first. dryRun: true returns the plan only. Steps that change live calls at once or delete something need confirm: true after the user agrees; the refusal names them. Returns the validate_agent result. Never publishes.