apicheats.dev anthropic/llms.txt Raw .md
POST

POST /v1/agents/{agent_id}?beta=true — Claude API

Beta

Anthropic API key (required); https://api.anthropic.com

Claude API

Update Agent

Base URL
https://api.anthropic.com
Auth
x-api-key: <ANTHROPIC_API_KEY>
Last verified
2026-10-20 · upstream hash matched
Actions Try in browser→
Agents: curl -H "Accept: text/markdown" this URL
→ 372 tokens · Vary: Accept

Critical gotchas

Authentication uses the x-api-key header and requests also require an anthropic-version header.

The official OpenAPI URL is discovered from the SDK repository manifest and must remain under Anthropic's trusted Stainless storage prefix.

cURL

curl -X POST 'https://api.anthropic.com/v1/agents/agent-id?beta=true' \  -H "x-api-key: $ANTHROPIC_API_KEY" \  -H 'anthropic-version: 2023-06-01' \  -H 'Content-Type: application/json' \  -d '{  "description": "updated"}'

Parameters

Name In Type Required Description
agent_id path string Yes Path parameter agent_id
version body integer No 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.
name body string No Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.
description body string No Description. Omit to preserve; send empty string or null to clear.
model body string No Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-5`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared.
system body string No System prompt. Omit to preserve; send empty string or null to clear.
tools body object[] No Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed.
mcp_servers body object[] No MCP servers. Full replacement. Omit to preserve; send empty array or `null` to clear. Names must be unique. Maximum 20. Every server must be referenced by an `mcp_toolset` in the agent's resulting `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector).
skills body object[] No Skills. Full replacement. Omit to preserve; send empty array or null to clear.
metadata body object No 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.
multiagent body object No Multiagent orchestration configuration. Full replacement. Omit to preserve; send null to clear.

Response 200 OK

{
  "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
}
Get a free Claude API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.