Agents

Update an agent

Changed on

Partially update an agent's name, description or owner_id.

Only the fields present in the body change; an empty body returns the agent unchanged. Allowed for the agent's owner or an org:admin (anyone else gets 404). Changing owner_id transfers ownership, is org:admin-only, and revokes every active OAuth client grant bound to the agent, so the new owner must re-consent any connected client. The agent's API key, permissions and credential bindings are unaffected. An archived agent cannot be updated (409). Returns the updated agent.

patch/agents/{agent_id}

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /agents/{agent_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL /authorize, token URL /oauth/token)

Path parameters

agent_idstring required

ID of the agent.

Example:agnt_6968b3984d1c238dbe7e2e29

Request body

descriptionstring nullable

New description for the agent.

namestring nullable

New name for the agent.

owner_idstring nullable

ID of the user to transfer ownership to; org:admin only.

Example request

{
  "description": "Reconciles Stripe invoices against the ledger every night.",
  "name": "invoice-reconciler",
  "owner_id": "usr_6968b3987ee4c3ec0b4ee3b9"
}

Response

Successful Response

approved_atstring date-time nullable

When the agent was approved (RFC 3339); null if not approved.

approved_bystring nullable

ID of the user who approved the agent; null if not approved.

created_atstring date-time required

When the agent was created (RFC 3339).

denial_reasonstring nullable

Reason given when the agent was denied; null if not denied.

denied_bystring nullable

ID of the actor that denied the agent; null if not denied.

descriptionstring nullable

Free-text description of the agent; null if not set.

has_api_keyboolean

Whether the agent currently has an active API key; only populated by GET /agents/{agent_id}, and false in other responses.

idstring required

Unique ID of the agent.

namestring required

Human-readable name of the agent.

owner_idstring nullable

ID of the user who owns the agent; null for an unclaimed self-registration.

parent_agent_idstring nullable

ID of the parent agent; null when the agent has no parent.

registered_bystring required

ID of the actor that registered the agent, or self for a self-registration.

statusstring required

Lifecycle status of the agent: pending, active, rejected, disabled or archived.

Example response

{
  "approved_at": "2026-01-15T09:45:00Z",
  "approved_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "created_at": "2026-01-15T09:30:00Z",
  "denial_reason": "Requested permissions exceed the agent's stated purpose.",
  "denied_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "description": "Reconciles Stripe invoices against the ledger every night.",
  "has_api_key": true,
  "id": "agnt_6968b3984d1c238dbe7e2e29",
  "name": "invoice-reconciler",
  "owner_id": "usr_6968b3987ee4c3ec0b4ee3b9",
  "parent_agent_id": "agnt_6968b3984d1c238dbe7e2e29",
  "registered_by": "usr_6968b3987ee4c3ec0b4ee3b9",
  "status": "active"
}

Changes