Skip to main content
PATCH
cURL
Send only the abilities you want to change. Enabling an ability that is already on keeps its saved settings unless you send new ones. Abilities your organization’s policy denies (for example Browser) answer 403.

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 a custom agent.

Body

application/json

Native abilities. On PATCH /agents/{agent_id}/abilities send only the ones you want to change; each is a small object so settings travel with the toggle.

web_fetch
object
image_generation
object
search_past_conversations
object
ask_question
object

Whether the agent may pause to ask the person a question.

tool_discovery
object
deprecated

Deprecated and ignored: every agent reaches its connectors through search and tool_call. Reads return enabled; a write that sends it is accepted, not applied, and reported in deprecations. Removed in the next release.

manage_evaluations
object
chat_widgets
object

Compact visuals in web chats. On by default for new custom agents; enable explicitly on older agents. Represented in tools by {"type": "chat_widget"}.

browser
object

Include enabled: true when updating browser options and keeping the ability on. Omitting the browser object preserves the ability and its saved options.

version
integer

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

Response

The agent's abilities after the change.

agent_id
string
Example:

"abc123DEFghiJKL"

abilities
object

Native abilities. On PATCH /agents/{agent_id}/abilities send only the ones you want to change; each is a small object so settings travel with the toggle.

version
integer | null
Example:

5

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.