Agents
Agents

Get an agent's full configuration

Return the full current agent snapshot as JSON, the agent row (name, voice, model, settings), the current version's system prompt + greeting, the tool list (each tool's name, kind, description, and for HTTP tools its url/method/headers/params/mock), the `workflow` (pre-call and post-call functions), variables (name + kind; secret values are never returned, plain values are), and the `privacy` block (recording + AI consent-disclosure enabled flags + copy, PII scrub level/categories, retention, telemetry, call-recording, null on an enabled flag means it inherits the workspace default). In the in-app builder this snapshot is already inlined every turn so calling it is just a post-edit re-read; over MCP it is the ONLY way to read the prompt/tools/variables/privacy, so call it whenever you need to see current state or confirm an edit landed. Pass `version: 'published'` (or a version number) to read the live version while a draft is open. For a cheap re-read after an edit, pass `toolName` (one tool's entry) or `sections` (only the groups you need, prompt/tools/variables/voice/behaviour/privacy/settings/model/workflow) instead of pulling the whole ~50KB snapshot. In the `model` group, `judgeModel` names the grading model (null = the platform default).

GET
/workspaces/{workspace}/agents/{agent}

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.

Query Parameters

sections?array<>

Scope the read to only these snapshot groups (plus the tiny agent identity header, always included). Omit for the full snapshot. Allowed: prompt, tools, variables, voice, behaviour, privacy, settings, model, workflow. Use this for a cheap re-read after an edit instead of pulling the whole ~50KB snapshot. privacy surfaces the Data & Privacy overrides, the recording + AI consent-disclosure enabled flags and their copy, PII scrub level/categories, retention, telemetry and call-recording (null on an enabled flag = inherits the workspace default).

Items1 <= items
toolName?string

Return only this one tool's full entry (resolved by snake_case name) instead of the whole tool list, the cheap re-read after editing a single tool. If sections is also given, this scopes the tools section.

Length1 <= length
version?|

Read a version other than the latest: "published" for the version live calls use, or a version number. Omit for the latest version (the draft when there is one). Use it to read or copy the published prompt while a draft is open.

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 GET "https://example.com/workspaces/string/agents/string"
{
  "systemPrompt": "string",
  "tools": [
    {
      "id": "string",
      "name": "string",
      "kind": "string",
      "property1": null,
      "property2": null
    }
  ],
  "variables": [
    {
      "name": "string",
      "kind": "string",
      "hasValue": true,
      "property1": null,
      "property2": null
    }
  ],
  "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
}

Duplicate an agent POST

Copy this agent into a new agent, in the same workspace or in the one `workspace` names, and return the new agent's handle. `agent` is the SOURCE to copy; `name` is the new agent's display name (its slug is derived from the name). Pass `workspace` to move an agent to another workspace you hold workspace-wide edit access in: the copy carries everything below, and the original keeps its calls, phone numbers and lead callback until you move them. Copied: the source's latest version content (system prompt, inbound, returning and outbound greetings, workflow, model and version settings) as an unpublished draft version 1, every tool row (order, kind, parameters, HTTP endpoint and headers, mocks, requires, follow-up, response template), every variable (plain, secret and default-only; secret values are stored again server-side for the new agent and never returned), and the agent-row call-handling config (settings, model, realtime, voice, keyterms, PII and retention). Copying the variables needs edit access to the source; the result lists the copied variable names and kinds under `variablesCopied`. When any variable is not copied, `variablesError` says why and `variablesNotCopied` lists every such name with its reason; the rest are still copied, so re-enter only those. NOT copied: tests and scenarios, phone numbers, the public share link, and knowledge-base sources. The duplicate starts unpublished and takes no calls until you call publish_version. Use it to fork a working agent for a second location or a variant you want to change without touching the original, or to hand an agent to another workspace; use create_agent instead when you want the house scaffold.

List agents GET

List the agents you can access, each with its handle ('workspace-slug/agent-slug'), name, published status, active flag, and last-updated time. Archived agents are hidden by default (matching the app's agents list); pass include_archived: true to see them too (each carries an `archived` flag, so you can find one to restore_agent). Optionally scope to one workspace by slug. Call this to discover what exists before editing; every agent-scoped tool needs the exact handle.