1# Managed Agents — Endpoint Reference
2 
3All endpoints require `x-api-key` and `anthropic-version: 2023-06-01` headers. Managed Agents endpoints additionally require the `anthropic-beta` header.
4 
5## Beta Headers
6 
7```
8anthropic-beta: managed-agents-2026-04-01
9```
10 
11The SDK adds this header automatically for all `client.beta.{agents,environments,sessions,vaults,memory_stores}.*` calls. Skills endpoints use `skills-2025-10-02`; Files endpoints use `files-api-2025-04-14`.
12 
13---
14 
15## SDK Method Reference
16 
17All resources are under the `beta` namespace. Python and TypeScript share identical method names.
18 
19| Resource | Python / TypeScript (`client.beta.*`) | Go (`client.Beta.*`) |
20| --- | --- | --- |
21| Agents | `agents.create` / `retrieve` / `update` / `list` / `archive` | `Agents.New` / `Get` / `Update` / `List` / `Archive` |
22| Agent Versions | `agents.versions.list` | `Agents.Versions.List` |
23| Environments | `environments.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Environments.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
24| Sessions | `sessions.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Sessions.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
25| Session Events | `sessions.events.list` / `send` / `stream` | `Sessions.Events.List` / `Send` / `StreamEvents` |
26| Session Threads | `sessions.threads.list` / `retrieve` / `archive`; `sessions.threads.events.list` / `stream` | `Sessions.Threads.List` / `Get` / `Archive`; `Sessions.Threads.Events.List` / `StreamEvents` |
27| Session Resources | `sessions.resources.add` / `retrieve` / `update` / `list` / `delete` | `Sessions.Resources.Add` / `Get` / `Update` / `List` / `Delete` |
28| Vaults | `vaults.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
29| Credentials | `vaults.credentials.create` / `retrieve` / `update` / `list` / `delete` / `archive` / `mcp_oauth_validate` | `Vaults.Credentials.New` / `Get` / `Update` / `List` / `Delete` / `Archive` / `McpOauthValidate` |
30| Memory Stores | `memory_stores.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `MemoryStores.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
31| Memories | `memory_stores.memories.create` / `retrieve` / `update` / `list` / `delete` | `MemoryStores.Memories.New` / `Get` / `Update` / `List` / `Delete` |
32| Memory Versions | `memory_stores.memory_versions.list` / `retrieve` / `redact` | `MemoryStores.MemoryVersions.List` / `Get` / `Redact` |
33 
34**Naming quirks to watch for:**
35- Agents and Session Threads have **no delete** — only `archive`. Archive is **permanent**: the agent becomes read-only, new sessions cannot reference it, and there is no unarchive. Confirm with the user before archiving a production agent. Environments, Sessions, Vaults, Credentials, and Memory Stores have both `delete` and `archive`; Session Resources, Files, Skills, and Memories are `delete`-only; Memory Versions have neither — only `redact`.
36- Session resources use `add` (not `create`).
37- Go's event stream is `StreamEvents` (not `Stream`).
38 
39**Agent shorthand:** `agent` on session create accepts either a bare string (`agent="agent_abc123"` — uses latest version) or the full reference object (`{type: "agent", id: "agent_abc123", version: 123}`).
40 
41**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-4-7"` — uses `standard` speed) or the full config object (`{type: "model_config", id: "claude-opus-4-6", speed: "fast"}`). Note: `speed: "fast"` is only supported on Opus 4.6.
42 
43---
44 
45## Agents
46 
47**Step one of every flow.** Sessions require a pre-created agent — there is no inline agent config under `managed-agents-2026-04-01`.
48 
49| Method   | Path                                             | Operation        | Description                              |
50| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
51| `GET` | `/v1/agents` | ListAgents | List agents |
52| `POST` | `/v1/agents` | CreateAgent | Create a saved agent configuration |
53| `GET` | `/v1/agents/{agent_id}` | GetAgent | Get agent details |
54| `POST` | `/v1/agents/{agent_id}` | UpdateAgent | Update agent configuration |
55| `POST` | `/v1/agents/{agent_id}/archive` | ArchiveAgent | Archive an agent. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
56| `GET` | `/v1/agents/{agent_id}/versions` | ListAgentVersions | List agent versions |
57 
58## Sessions
59 
60| Method   | Path                                             | Operation        | Description                              |
61| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
62| `GET` | `/v1/sessions` | ListSessions | List sessions (paginated) |
63| `POST` | `/v1/sessions` | CreateSession | Create a new session |
64| `GET` | `/v1/sessions/{session_id}` | GetSession | Get session details |
65| `POST` | `/v1/sessions/{session_id}` | UpdateSession | Update session metadata/title |
66| `DELETE` | `/v1/sessions/{session_id}` | DeleteSession | Delete a session |
67| `POST` | `/v1/sessions/{session_id}/archive` | ArchiveSession | Archive a session |
68 
69## Events
70 
71| Method   | Path                                             | Operation        | Description                              |
72| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
73| `GET` | `/v1/sessions/{session_id}/events` | ListEvents | List events (polling, paginated) |
74| `POST` | `/v1/sessions/{session_id}/events` | SendEvents | Send events (user message, tool result) |
75| `GET` | `/v1/sessions/{session_id}/events/stream` | StreamEvents | Stream events via SSE |
76 
77## Session Threads
78 
79Per-subagent event streams in multiagent sessions. See `shared/managed-agents-multiagent.md`.
80 
81| Method   | Path                                             | Operation        | Description                              |
82| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
83| `GET` | `/v1/sessions/{session_id}/threads` | ListThreads | List threads (paginated) |
84| `GET` | `/v1/sessions/{session_id}/threads/{thread_id}` | GetThread | Retrieve one thread (carries `agent` snapshot, `status`, `parent_thread_id`, `stats`, `usage`) |
85| `POST` | `/v1/sessions/{session_id}/threads/{thread_id}/archive` | ArchiveThread | Archive a thread |
86| `GET` | `/v1/sessions/{session_id}/threads/{thread_id}/events` | ListThreadEvents | List past events for one thread (paginated) |
87| `GET` | `/v1/sessions/{session_id}/threads/{thread_id}/stream` | StreamThreadEvents | Stream one thread via SSE (SDK: `threads.events.stream`) |
88 
89## Session Resources
90 
91| Method   | Path                                                    | Operation        | Description                              |
92| -------- | ------------------------------------------------------- | ---------------- | ---------------------------------------- |
93| `GET` | `/v1/sessions/{session_id}/resources` | ListResources | List resources attached to session |
94| `POST` | `/v1/sessions/{session_id}/resources` | AddResource | Attach `file` or `github_repository` resource (SDK method: `add`, not `create`). `memory_store` resources attach at session-create time only. |
95| `GET` | `/v1/sessions/{session_id}/resources/{resource_id}` | GetResource | Get a single resource |
96| `POST` | `/v1/sessions/{session_id}/resources/{resource_id}` | UpdateResource | Update resource |
97| `DELETE` | `/v1/sessions/{session_id}/resources/{resource_id}` | DeleteResource | Remove resource from session |
98 
99## Environments
100 
101| Method   | Path                                                             | Operation            | Description                         |
102| -------- | ---------------------------------------------------------------- | -------------------- | ----------------------------------- |
103| `POST`   | `/v1/environments`                                     | CreateEnvironment    | Create environment                  |
104| `GET`    | `/v1/environments`                                     | ListEnvironments     | List environments                   |
105| `GET`    | `/v1/environments/{environment_id}`                    | GetEnvironment       | Get environment details             |
106| `POST`   | `/v1/environments/{environment_id}`                    | UpdateEnvironment    | Update environment                  |
107| `DELETE` | `/v1/environments/{environment_id}`                    | DeleteEnvironment    | Delete environment. Returns 204. |
108| `POST`   | `/v1/environments/{environment_id}/archive`            | ArchiveEnvironment   | Archive environment. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
109 
110## Vaults
111 
112Vaults store MCP credentials that Anthropic manages on your behalf — OAuth credentials with auto-refresh, or static bearer tokens. Attach to sessions via `vault_ids`. See `managed-agents-tools.md` §Vaults for the conceptual guide and credential shapes.
113 
114| Method   | Path                                             | Operation        | Description                              |
115| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
116| `POST`   | `/v1/vaults`                                     | CreateVault      | Create a vault                           |
117| `GET`    | `/v1/vaults`                                     | ListVaults       | List vaults                              |
118| `GET`    | `/v1/vaults/{vault_id}`                          | GetVault         | Get vault details                        |
119| `POST`   | `/v1/vaults/{vault_id}`                          | UpdateVault      | Update vault                             |
120| `DELETE` | `/v1/vaults/{vault_id}`                          | DeleteVault      | Delete vault                             |
121| `POST`   | `/v1/vaults/{vault_id}/archive`                  | ArchiveVault     | Archive vault                            |
122 
123## Credentials
124 
125Credentials are individual secrets stored inside a vault.
126 
127| Method   | Path                                                              | Operation          | Description                  |
128| -------- | ----------------------------------------------------------------- | ------------------ | ---------------------------- |
129| `POST`   | `/v1/vaults/{vault_id}/credentials`                               | CreateCredential   | Create a credential          |
130| `GET`    | `/v1/vaults/{vault_id}/credentials`                               | ListCredentials    | List credentials in vault    |
131| `GET`    | `/v1/vaults/{vault_id}/credentials/{credential_id}`               | GetCredential      | Get credential metadata      |
132| `POST`   | `/v1/vaults/{vault_id}/credentials/{credential_id}`               | UpdateCredential   | Update credential            |
133| `DELETE` | `/v1/vaults/{vault_id}/credentials/{credential_id}`               | DeleteCredential   | Delete credential            |
134| `POST`   | `/v1/vaults/{vault_id}/credentials/{credential_id}/archive`       | ArchiveCredential  | Archive credential           |
135| `POST`   | `/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate` | McpOauthValidate | Validate an MCP OAuth credential |
136 
137## Memory Stores
138 
139Workspace-scoped persistent memory that survives across sessions. Attach to a session via a `{"type": "memory_store", "memory_store_id": ...}` entry in `resources[]` (session-create time only). See `shared/managed-agents-memory.md` for the conceptual guide, the FUSE-mount agent interface, preconditions, and versioning.
140 
141| Method   | Path                                             | Operation          | Description                              |
142| -------- | ------------------------------------------------ | ------------------ | ---------------------------------------- |
143| `POST`   | `/v1/memory_stores`                              | CreateMemoryStore  | Create a store (`name`, `description`, `metadata`) |
144| `GET`    | `/v1/memory_stores`                              | ListMemoryStores   | List stores (`include_archived`, `created_at_{gte,lte}`) |
145| `GET`    | `/v1/memory_stores/{memory_store_id}`            | GetMemoryStore     | Get store details                        |
146| `POST`   | `/v1/memory_stores/{memory_store_id}`            | UpdateMemoryStore  | Update store                             |
147| `DELETE` | `/v1/memory_stores/{memory_store_id}`            | DeleteMemoryStore  | Delete store                             |
148| `POST`   | `/v1/memory_stores/{memory_store_id}/archive`    | ArchiveMemoryStore | Archive store. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive. |
149 
150## Memories
151 
152Individual text documents inside a store (≤ 100KB each). `create` creates at a `path` and returns `409` (`memory_path_conflict_error`, with `conflicting_memory_id`) if the path is occupied; `update` mutates by `mem_...` ID (rename and/or content). Only `update` accepts a `precondition` (`{"type": "content_sha256", "content_sha256": ...}`) — on mismatch returns `409` (`memory_precondition_failed_error`). List endpoints accept `view: "basic"|"full"` (controls whether `content` is populated; `retrieve` defaults to `full`).
153 
154| Method   | Path                                                              | Operation      | Description                              |
155| -------- | ----------------------------------------------------------------- | -------------- | ---------------------------------------- |
156| `GET`    | `/v1/memory_stores/{memory_store_id}/memories`                    | ListMemories   | Returns `Memory \| MemoryPrefix`; filter by `path_prefix`, `depth`, `order_by`/`order` |
157| `POST`   | `/v1/memory_stores/{memory_store_id}/memories`                    | CreateMemory   | Create at `path` (SDK: `memories.create`); `409 memory_path_conflict_error` if occupied |
158| `GET`    | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`        | GetMemory      | Read one memory (defaults to `view="full"`) |
159| `PATCH`  | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`        | UpdateMemory   | Change `content`, `path`, or both by ID; optional `precondition` |
160| `DELETE` | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`        | DeleteMemory   | Delete (optional `expected_content_sha256`) |
161 
162## Memory Versions
163 
164Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surface. `operation` ∈ `created` / `modified` / `deleted`.
165 
166| Method   | Path                                                                          | Operation             | Description                              |
167| -------- | ----------------------------------------------------------------------------- | --------------------- | ---------------------------------------- |
168| `GET`    | `/v1/memory_stores/{memory_store_id}/memory_versions`                         | ListMemoryVersions    | Newest-first; filter by `memory_id`, `operation`, `session_id`, `api_key_id`, `created_at_{gte,lte}` |
169| `GET`    | `/v1/memory_stores/{memory_store_id}/memory_versions/{version_id}`            | GetMemoryVersion      | List fields + full `content`             |
170| `POST`   | `/v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact`     | RedactMemoryVersion   | Clear `content`/`content_sha256`/`content_size_bytes`/`path`; preserve actor + timestamps |
171 
172## Files
173 
174| Method   | Path                                             | Operation        | Description                              |
175| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
176| `POST`   | `/v1/files`                            | UploadFile       | Upload a file                            |
177| `GET`    | `/v1/files`                            | ListFiles        | List files                               |
178| `GET`    | `/v1/files/{file_id}`                  | GetFile          | Get file metadata (SDK method: `retrieve_metadata`) |
179| `GET`    | `/v1/files/{file_id}/content`          | DownloadFile     | Download file content                    |
180| `DELETE` | `/v1/files/{file_id}`                  | DeleteFile       | Delete a file                            |
181 
182## Skills
183 
184| Method   | Path                                                            | Operation          | Description                  |
185| -------- | --------------------------------------------------------------- | ------------------ | ---------------------------- |
186| `POST`   | `/v1/skills`                                          | CreateSkill        | Create a skill               |
187| `GET`    | `/v1/skills`                                          | ListSkills         | List skills                  |
188| `GET`    | `/v1/skills/{skill_id}`                               | GetSkill           | Get skill details            |
189| `DELETE` | `/v1/skills/{skill_id}`                               | DeleteSkill        | Delete a skill               |
190| `POST`   | `/v1/skills/{skill_id}/versions`                      | CreateVersion      | Create skill version         |
191| `GET`    | `/v1/skills/{skill_id}/versions`                      | ListVersions       | List skill versions          |
192| `GET`    | `/v1/skills/{skill_id}/versions/{version}`            | GetVersion         | Get skill version            |
193| `DELETE` | `/v1/skills/{skill_id}/versions/{version}`            | DeleteVersion      | Delete skill version         |
194 
195---
196 
197## Request/Response Schema Quick Reference
198 
199### CreateAgent Request Body
200 
201**Always start here.** `model`, `system`, `tools`, `mcp_servers`, `skills` are top-level fields on this object — they do NOT go on the session.
202 
203```json
204{
205  "name": "string (required, 1-256 chars)",
206  "model": "claude-opus-4-7 (required — bare string, or {id, speed} object)",
207  "description": "string (optional, up to 2048 chars)",
208  "system": "string (optional, up to 100,000 chars)",
209  "tools": [
210    { "type": "agent_toolset_20260401" }
211  ],
212  "skills": [
213    { "type": "anthropic", "skill_id": "xlsx" },
214    { "type": "custom", "skill_id": "skill_abc123", "version": "1" }
215  ],
216  "mcp_servers": [
217    {
218      "type": "url",
219      "name": "github",
220      "url": "https://api.githubcopilot.com/mcp/"
221    }
222  ],
223  "multiagent": {
224    "type": "coordinator",
225    "agents": [
226      "agent_abc123",
227      { "type": "agent", "id": "agent_def456", "version": 4 },
228      { "type": "self" }
229    ]
230  },
231  "metadata": {
232    "key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)"
233  }
234}
235```
236 
237> Limits: `tools` max 128, `skills` max 20, `mcp_servers` max 20 (unique names). `multiagent.agents` 1–20 entries (string ID | `{type:"agent",id,version?}` | `{type:"self"}`) — see `shared/managed-agents-multiagent.md`.
238 
239### CreateSession Request Body
240 
241```json
242{
243  "agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)",
244  "environment_id": "env_abc123 (required)",
245  "title": "string (optional)",
246  "resources": [
247    {
248      "type": "github_repository",
249      "url": "https://github.com/owner/repo (required)",
250      "authorization_token": "ghp_... (required)",
251      "mount_path": "/workspace/repo (optional — defaults to /workspace/<repo-name>)",
252      "checkout": { "type": "branch", "name": "main" }
253    }
254  ],
255  "vault_ids": ["vlt_abc123 (optional — MCP credentials with auto-refresh)"],
256  "metadata": {
257    "key": "value"
258  }
259}
260```
261 
262> The `agent` field accepts only a string ID or `{type: "agent", id, version}` — `model`/`system`/`tools` live on the agent, not here.
263>
264> **`checkout`** accepts `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Omit for the repo's default branch.
265 
266### CreateEnvironment Request Body
267 
268```json
269{
270  "name": "string (required)",
271  "description": "string (optional)",
272  "config": {
273    "type": "cloud",
274    "networking": {
275      "type": "unrestricted | limited (union — see SDK types)"
276    },
277    "packages": { }
278  },
279  "metadata": { "key": "value" }
280}
281```
282 
283### SendEvents Request Body
284 
285```json
286{
287  "events": [
288    {
289      "type": "user.message",
290      "content": [
291        {
292          "type": "text",
293          "text": "Hello"
294        }
295      ]
296    }
297  ]
298}
299```
300 
301### Define Outcome Event
302 
303```json
304{
305  "type": "user.define_outcome",
306  "description": "Build a DCF model for Costco in .xlsx",
307  "rubric": { "type": "file", "file_id": "file_01..." },
308  "max_iterations": 5
309}
310```
311 
312> `rubric` is required: `{type: "text", content}` or `{type: "file", file_id}`. `max_iterations` default 3, max 20. Echoed back with `outcome_id` + `processed_at`. See `shared/managed-agents-outcomes.md`.
313 
314### Tool Result Event
315 
316```json
317{
318  "type": "user.custom_tool_result",
319  "custom_tool_use_id": "sevt_abc123",
320  "content": [{ "type": "text", "text": "Result data" }],
321  "is_error": false
322}
323```
324 
325---
326 
327## Error Handling
328 
329Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing `type`, `error`, and `request_id`:
330 
331```json
332{
333  "type": "error",
334  "error": {
335    "type": "invalid_request_error",
336    "message": "Description of what went wrong"
337  },
338  "request_id": "req_011CRv1W3XQ8XpFikNYG7RnE"
339}
340```
341 
342Include the `request_id` when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner `error.type` is one of the following:
343 
344| Status | Error type | Description |
345|---|---|---|
346| 400 | `invalid_request_error` | The request was malformed or missing required parameters |
347| 401 | `authentication_error` | Invalid or missing API key |
348| 403 | `permission_error` | The API key doesn't have permission for this operation |
349| 404 | `not_found_error` | The requested resource doesn't exist |
350| 409 | `invalid_request_error` | The request conflicts with the resource's current state (e.g., sending to an archived session) |
351| 413 | `request_too_large` | The request body exceeds the maximum allowed size |
352| 429 | `rate_limit_error` | Too many requests — check rate limit headers for retry timing |
353| 500 | `api_error` | An internal server error occurred |
354| 529 | `overloaded_error` | The service is temporarily overloaded — retry with backoff |
355 
356Note that `409 Conflict` carries `error.type: "invalid_request_error"` (there is no separate `conflict_error` type); inspect both the HTTP status and the `message` to distinguish conflicts from other invalid requests.
357 
358---
359 
360## Rate Limits
361 
362Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your [Messages API token limits](https://platform.claude.com/docs/en/api/rate-limits). Model inference inside a session still draws from your organization's standard ITPM/OTPM limits.
363 
364| Endpoint group | Scope | RPM | Max concurrent |
365|---|---|---|---|
366| Create operations (Agents, Sessions, Vaults) | organization | 60 | — |
367| All other operations (Agents, Sessions, Vaults) | organization | 600 | — |
368| All operations (Environments) | organization | 60 | 5 |
369 
370Files and Skills endpoints use the standard tier-based [rate limits](https://platform.claude.com/docs/en/api/rate-limits).
371 
372When a limit is exceeded the API returns `429` with a `rate_limit_error` (see [Error Handling](#error-handling) for the response envelope) and a `retry-after` header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically.
373