Update Agent

post/v1/agents/{agent_id}?beta=true

Path parameters

agent_idstring required

Path parameter agent_id

Headers

anthropic-versionstring

anthropic-betastring

Request body

versioninteger

The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. Must be at least 1 if specified. When supplied, the request fails if it does not match the server's current version; omit to apply the update unconditionally.

namestring

Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.

descriptionstring nullable

Description. Omit to preserve; send empty string or null to clear.

systemstring nullable

System prompt. Omit to preserve; send empty string or null to clear.

metadataobject nullable

Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.

Example request

{
  "version": 1,
  "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end."
}

Response

Successful response (OK)

type'agent' required

idstring required

versioninteger required

The agent's current version. Starts at 1 and increments when the agent is modified.

namestring required

descriptionstring nullable required

systemstring nullable required

metadataobject required

created_atstring date-time required

A timestamp in RFC 3339 format

updated_atstring date-time required

A timestamp in RFC 3339 format

archived_atstring date-time required

A timestamp in RFC 3339 format

Example response

{
  "type": "agent",
  "id": "agent_011CZkYpogX7uDKUyvBTophP",
  "version": 1,
  "name": "My First Agent",
  "description": "A general-purpose starter agent.",
  "model": {
    "id": "claude-opus-5",
    "speed": "standard"
  },
  "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "configs": []
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "example-mcp",
      "url": "https://example-server.modelcontextprotocol.io/sse"
    }
  ],
  "skills": [
    {
      "type": "anthropic",
      "skill_id": "xlsx",
      "version": "1"
    },
    {
      "type": "custom",
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "version": "2"
    }
  ],
  "multiagent": null,
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z",
  "archived_at": null
}

Changes

Changed in 14 of the 68 revisions of this API.28755

Sep 1, 2026d1d189d791d13See the full diff
- ○
  added subschema #2 to the ///////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the ////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the / response property anyOf list for the response status
  response-property-any-of-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 19, 20260042750ea1ee433See the full diff
- ▲
  added to the /////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  removed the required property //////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////// from the response with the status
  response-required-property-removed
- ●
  removed the request property /////////
  request-property-removed
- ●
  removed the request property /////////
  request-property-removed
- ●
  removed the request property /////////
  request-property-removed
- ○
  added discriminator to //////// request property
  request-property-discriminator-added
- ○
  added to the //////// request property oneOf list
  request-property-one-of-added
- ○
  added discriminator to /////// response property for the response status
  response-property-discriminator-added
Aug 17, 2026d2b230555b7f12314See the full diff
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property ///////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property ///////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property ///////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  response property description list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property system list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ●
  removed from the ///////// request property allOf list
  request-property-all-of-removed
- ●
  removed from the request property allOf list
  request-property-all-of-removed
- ●
  removed from the ///////// request property allOf list
  request-property-all-of-removed
- ○
  added subschema #2 to the ///////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the ///////// request property anyOf list
  request-property-any-of-added
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property ///////// list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  removed from the response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed from the response property allOf list for the response status
  response-property-all-of-removed
- ○
  added subschema #2 to the response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the response property anyOf list for the response status
  response-property-any-of-added
Aug 6, 202693d8fd7d649355See the full diff
- ▲
  added to the ////////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  the ////////// response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  removed the required property /////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property /////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property /////////// from the response with the status
  response-required-property-removed
- ○
  added the new optional request property /////////
  new-optional-request-property
- ○
  added advisor discriminator mapping keys to the /////////// request property
  request-property-discriminator-mapping-added
- ○
  added to the /////////// request property oneOf list
  request-property-one-of-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added discriminator to ////////// response property for the response status
  response-property-discriminator-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 24, 2026a97790bd7f1824See the full diff
- ▲
  removed subschema #4 subschema #5 subschema #6 subschema #10 subschema #11 from the ///////// request property anyOf list
  request-property-any-of-removed
- ▲
  removed subschema #4 subschema #5 subschema #6 subschema #10 subschema #11 from the ////// request property anyOf list
  request-property-any-of-removed
- ○
  added subschema #4 subschema #5 subschema #6 subschema #7 subschema #11 subschema #12 to the ///////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #4 subschema #5 subschema #6 subschema #7 subschema #11 subschema #12 to the ////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #4 subschema #5 subschema #6 subschema #7 subschema #11 subschema #12 to the / response property anyOf list for the response status
  response-property-any-of-added
- ○
  removed subschema #4 subschema #5 subschema #6 subschema #10 subschema #11 from the / response property anyOf list for the response status
  response-property-any-of-removed
Jul 22, 20265e4a8830793b3See the full diff
- ○
  added the new optional request property /////////
  new-optional-request-property
- ○
  the request property became optional
  request-property-became-optional
- ○
  added the optional property / to the response with the status
  response-optional-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 2, 2026ec00b28b50c21See the full diff
- ○
  the ////// request property's maxLength was increased from 1024 to 4096
  request-property-max-length-increased
Jun 30, 20267caa9a75ddbc3See the full diff
- ○
  added subschema #2 to the ///////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the ////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the / response property anyOf list for the response status
  response-property-any-of-added
Jun 9, 202600259327305f3See the full diff
- ○
  added subschema #2 to the ///////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the ////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the / response property anyOf list for the response status
  response-property-any-of-added
Jun 6, 2026546c704d347b517See the full diff
- ▲
  the request property /////////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property /////////// became required
  request-property-became-required
- ▲
  the request property const value object was added
  request-property-const-added
- ▲
  removed the enum value object of the request property ///////////
  request-property-enum-value-removed
- ▲
  response property tools/items/oneOf[BetaManagedAgentsCustomTool]/input_schema/required list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ●
  removed from the /////////// request property allOf list
  request-property-all-of-removed
- ○
  added subschema #1 subschema #2 to the /////////// request property anyOf list
  request-property-any-of-added
- ○
  request property /////////// list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  removed from the /////// response property allOf list for the response status
  response-property-all-of-removed
- ○
  added subschema #1 subschema #2 to the /////// response property anyOf list for the response status
  response-property-any-of-added
- ○
  the response property /////// became required for the status
  response-property-became-required
- ○
  the response property const value object was added for the status
  response-property-const-added
- ○
  removed the object enum value from the /////// response property for the response status
  response-property-enum-value-removed

Full history (14 revisions)