Docs
OverviewGuidesZero & MCPAPI referenceChangelog
Agents

Update Agent

Turn an agent on or off, pause or resume it, set its autonomy or its schedule (Prospector). Admins only. Customer-facing agents are capped at `ask_first` (422 `autonomy_cap`); the Writer and the Inbox agent may be `auto` while Email approval is `none`, set by a person in the app only (403 `human_only` from Zero, MCP or an API key). Autonomy changes are audited (`agent.autonomy_changed`).

API key access

Needs the agents:write scope with an API key (ro_pat_...). A signed-in session uses the caller's role.
PATCH/api/v1/agents/{agent}

Authorization

AuthorizationBearer <token>

Access token from /api/v1/auth/login, or an API key (ro_pat_..., RO-176) from /api/v1/workspaces/current/api-keys: the key implies its workspace and needs the route's scope. MCP connectors (/api/v1/mcp only) may use an OAuth access token (ro_oat_..., RO-284).

In: header

Path Parameters

agentstring

Header Parameters

X-Workspace-Id?string | null

Id of the workspace to act on (must be a member).

Request Body

enabled?boolean | null
paused?boolean | null
autonomy?AgentAutonomy | null
schedule?AgentScheduleIn | null

Response Body

curl -X PATCH "http://localhost:8000/api/v1/agents/string" \  -H "X-Workspace-Id: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "key": "prospector",
  "name": "string",
  "stage": "string",
  "description": "string",
  "available": true,
  "state": "coming_soon",
  "enabled": true,
  "paused": true,
  "paused_at": "2019-08-24T14:15:22Z",
  "autonomy": "suggest",
  "max_autonomy": "suggest",
  "auto_requires": "string",
  "customer_facing": true,
  "autonomy_effect": "string",
  "triggers": [
    "string"
  ],
  "schedulable": true,
  "schedule": {},
  "next_run_at": "2019-08-24T14:15:22Z",
  "pause_effect": "string",
  "settings_href": "string",
  "last_activity": {},
  "runs_today": 0,
  "updated_at": "2019-08-24T14:15:22Z"
}
Empty
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

List Agents

The eight agents with their settings, last activity and today's activity count.

Create Ai Column

Add a column defined by a prompt to the leads or companies table (RO-340). Nothing runs until a member runs it on rows. At most 10 per table (409 `ai_columns_limit`); `options` only for `classify` (2-12, 422 `options_required` / `options_not_allowed`).