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.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Path Parameters
Workspace slug (GET /me lists yours).
Agent slug within the workspace.
Header Parameters
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.
1 <= length <= 255Request 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.