Agents
Agents

Update an agent from a partial spec

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.

PATCH
/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.

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 PATCH "https://example.com/workspaces/string/agents/string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "applied": [
    null
  ],
  "alwaysAsk": [
    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
}