Skip to main content
PATCH
cURL
Collections have their own endpoints and one item changes per call: skills, connectors, knowledge sources, subagents, triggers and abilities. tools is still accepted and replaces the whole list; metadata.subagent.allowed_gummie_ids is ignored here.Send version from your last read to make the update conditional: if anyone saved the agent in between, the response is 409 agent_version_conflict with the current version. Omit it to let the last write win.To change incognito enforcement, use Set agent incognito. This endpoint rejects top-level incognito with 400 invalid_request and cannot change enforcement through metadata. Platform agents (orchestrivoassistant, analytics) answer 400 agent_not_customizable.is_active: false is not a pause switch. It retires the agent: the agent disappears from GET /agents, and both GET and PATCH /agents/{agent_id} return 404 afterwards, so you cannot set it back to true through the API. To stop an agent from running on its own while keeping it fully reachable, disable its triggers instead. To remove it, use DELETE /agents/{agent_id}.

Authorizations

Authorization
string
header
required

A personal API key or an OAuth 2.0 access token. Personal API keys also require the x-auth-key header with your user ID.

Path Parameters

agent_id
string
required

ID of the agent to update. Also accepts the reserved aliases orchestrivoassistant and analytics.

Body

application/json
name
string | null
model_name
string | null

ID of the LLM the agent runs on. Use GET /models to discover valid values.

Example:

"anthropic/claude-sonnet-4"

description
string | null
Example:

"Researches enterprise accounts and drafts outreach"

system_prompt
string | null
tools
object[] | null

When provided, replaces the agent's whole tool list. The native Chat Widgets entry is {"type": "chat_widget"}. Prefer the abilities and connector endpoints.

resources
object[] | null

When provided, replaces the agent's resource list.

metadata
object | null

Agent settings, grouped as the agent panel groups them. On PATCH, objects merge and arrays and scalars replace, except model_settings, which replaces the saved object whole. Unknown keys are dropped.

is_active
boolean | null

Setting this to false retires the agent: it disappears from GET /agents, and GET/PATCH /agents/{agent_id} return 404, so it cannot be reactivated through the API. This is not a pause switch — to stop an agent from running while keeping it reachable, disable its triggers instead.

team_id
string | null

When provided, transfers ownership of the agent to this team.

version
integer | null

The version you last read. The update is refused with 409 agent_version_conflict if the agent changed since.

Required range: x >= 1
Example:

4

Response

The updated agent.

agent
object

An agent and its whole configuration. Single-agent retrieve, create and update return this shape; the list endpoint does not populate the inlined collections, abilities or version. Collection-specific writes return their own result shapes.

deprecations
object[]

Present only when the request sent a retired field. Each entry names the field (dotted for nested, e.g. metadata.tool_discovery) and says what replaced it and when it is removed. The write itself succeeds with the field ignored.