Skip to main content
PATCH
cURL

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 gumball 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. 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, so send only the sections you want to change. 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.

Example:

4

Response

The updated agent.

agent
object

An agent and its whole configuration. Single-agent reads and every configuration write return this shape; the list endpoint omits the inlined collections.