Skip to content
Uvilo OS
approved Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Data: Managed Agents endpoint reference

Managed Agents — Endpoint Reference

All endpoints require x-api-key and anthropic-version: 2023-06-01 headers. Managed Agents endpoints additionally require the anthropic-beta header.

Beta Headers

anthropic-beta: managed-agents-2026-04-01

The 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.

SDK Method Reference

All resources are under the beta namespace. Python and TypeScript share identical method names.

ResourcePython / TypeScript (client.beta.*)Go (client.Beta.*)
Agentsagents.create / retrieve / update / list / archiveAgents.New / Get / Update / List / Archive
Agent Versionsagents.versions.listAgents.Versions.List
Environmentsenvironments.create / retrieve / update / list / delete / archiveEnvironments.New / Get / Update / List / Delete / Archive
Sessionssessions.create / retrieve / update / list / delete / archiveSessions.New / Get / Update / List / Delete / Archive
Session Eventssessions.events.list / send / streamSessions.Events.List / Send / StreamEvents
Session Resourcessessions.resources.add / retrieve / update / list / deleteSessions.Resources.Add / Get / Update / List / Delete
Vaultsvaults.create / retrieve / update / list / delete / archiveVaults.New / Get / Update / List / Delete / Archive
Credentialsvaults.credentials.create / retrieve / update / list / delete / archiveVaults.Credentials.New / Get / Update / List / Delete / Archive
Memory Storesmemory_stores.create / retrieve / update / list / delete / archiveMemoryStores.New / Get / Update / List / Delete / Archive
Memoriesmemory_stores.memories.create / retrieve / update / list / deleteMemoryStores.Memories.New / Get / Update / List / Delete
Memory Versionsmemory_stores.memory_versions.list / retrieve / redactMemoryStores.MemoryVersions.List / Get / Redact

Naming quirks to watch for:

  • Agents 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.
  • Session resources use add (not create).
  • Go’s event stream is StreamEvents (not Stream).

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}).

Model shorthand: model on agent create accepts either a bare string (model="{{OPUS_ID}}" — 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.

Agents

Step one of every flow. Sessions require a pre-created agent — there is no inline agent config under managed-agents-2026-04-01.

MethodPathOperationDescription
GET/v1/agentsListAgentsList agents
POST/v1/agentsCreateAgentCreate a saved agent configuration
GET/v1/agents/{agent_id}GetAgentGet agent details
POST/v1/agents/{agent_id}UpdateAgentUpdate agent configuration
POST/v1/agents/{agent_id}/archiveArchiveAgentArchive an agent. Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state.
GET/v1/agents/{agent_id}/versionsListAgentVersionsList agent versions

Sessions

MethodPathOperationDescription
GET/v1/sessionsListSessionsList sessions (paginated)
POST/v1/sessionsCreateSessionCreate a new session
GET/v1/sessions/{session_id}GetSessionGet session details
POST/v1/sessions/{session_id}UpdateSessionUpdate session metadata/title
DELETE/v1/sessions/{session_id}DeleteSessionDelete a session
POST/v1/sessions/{session_id}/archiveArchiveSessionArchive a session

Events

MethodPathOperationDescription
GET/v1/sessions/{session_id}/eventsListEventsList events (polling, paginated)
POST/v1/sessions/{session_id}/eventsSendEventsSend events (user message, tool result)
GET/v1/sessions/{session_id}/events/streamStreamEventsStream events via SSE

Session Resources

MethodPathOperationDescription
GET/v1/sessions/{session_id}/resourcesListResourcesList resources attached to session
POST/v1/sessions/{session_id}/resourcesAddResourceAttach file or github_repository resource (SDK method: add, not create). memory_store resources attach at session-create time only.
GET/v1/sessions/{session_id}/resources/{resource_id}GetResourceGet a single resource
POST/v1/sessions/{session_id}/resources/{resource_id}UpdateResourceUpdate resource
DELETE/v1/sessions/{session_id}/resources/{resource_id}DeleteResourceRemove resource from session

Environments

MethodPathOperationDescription
POST/v1/environmentsCreateEnvironmentCreate environment
GET/v1/environmentsListEnvironmentsList environments
GET/v1/environments/{environment_id}GetEnvironmentGet environment details
POST/v1/environments/{environment_id}UpdateEnvironmentUpdate environment
DELETE/v1/environments/{environment_id}DeleteEnvironmentDelete environment. Returns 204.
POST/v1/environments/{environment_id}/archiveArchiveEnvironmentArchive environment. Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state.

Vaults

Vaults 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.

MethodPathOperationDescription
POST/v1/vaultsCreateVaultCreate a vault
GET/v1/vaultsListVaultsList vaults
GET/v1/vaults/{vault_id}GetVaultGet vault details
POST/v1/vaults/{vault_id}UpdateVaultUpdate vault
DELETE/v1/vaults/{vault_id}DeleteVaultDelete vault
POST/v1/vaults/{vault_id}/archiveArchiveVaultArchive vault

Credentials

Credentials are individual secrets stored inside a vault.

MethodPathOperationDescription
POST/v1/vaults/{vault_id}/credentialsCreateCredentialCreate a credential
GET/v1/vaults/{vault_id}/credentialsListCredentialsList credentials in vault
GET/v1/vaults/{vault_id}/credentials/{credential_id}GetCredentialGet credential metadata
POST/v1/vaults/{vault_id}/credentials/{credential_id}UpdateCredentialUpdate credential
DELETE/v1/vaults/{vault_id}/credentials/{credential_id}DeleteCredentialDelete credential
POST/v1/vaults/{vault_id}/credentials/{credential_id}/archiveArchiveCredentialArchive credential

Memory Stores

Workspace-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.

MethodPathOperationDescription
POST/v1/memory_storesCreateMemoryStoreCreate a store (name, description, metadata)
GET/v1/memory_storesListMemoryStoresList stores (include_archived, created_at_{gte,lte})
GET/v1/memory_stores/{memory_store_id}GetMemoryStoreGet store details
POST/v1/memory_stores/{memory_store_id}UpdateMemoryStoreUpdate store
DELETE/v1/memory_stores/{memory_store_id}DeleteMemoryStoreDelete store
POST/v1/memory_stores/{memory_store_id}/archiveArchiveMemoryStoreArchive store. Makes it read-only; existing sessions continue, new sessions cannot reference it. No unarchive.

Memories

Individual 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).

MethodPathOperationDescription
GET/v1/memory_stores/{memory_store_id}/memoriesListMemoriesReturns Memory | MemoryPrefix; filter by path_prefix, depth, order_by/order
POST/v1/memory_stores/{memory_store_id}/memoriesCreateMemoryCreate at path (SDK: memories.create); 409 memory_path_conflict_error if occupied
GET/v1/memory_stores/{memory_store_id}/memories/{memory_id}GetMemoryRead one memory (defaults to view="full")
PATCH/v1/memory_stores/{memory_store_id}/memories/{memory_id}UpdateMemoryChange content, path, or both by ID; optional precondition
DELETE/v1/memory_stores/{memory_store_id}/memories/{memory_id}DeleteMemoryDelete (optional expected_content_sha256)

Memory Versions

Immutable per-mutation snapshots (memver_...) — the audit and rollback surface. operation ∈ created / modified / deleted.

MethodPathOperationDescription
GET/v1/memory_stores/{memory_store_id}/memory_versionsListMemoryVersionsNewest-first; filter by memory_id, operation, session_id, api_key_id, created_at_{gte,lte}
GET/v1/memory_stores/{memory_store_id}/memory_versions/{version_id}GetMemoryVersionList fields + full content
POST/v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redactRedactMemoryVersionClear content/content_sha256/content_size_bytes/path; preserve actor + timestamps

Files

MethodPathOperationDescription
POST/v1/filesUploadFileUpload a file
GET/v1/filesListFilesList files
GET/v1/files/{file_id}GetFileGet file metadata (SDK method: retrieve_metadata)
GET/v1/files/{file_id}/contentDownloadFileDownload file content
DELETE/v1/files/{file_id}DeleteFileDelete a file

Skills

MethodPathOperationDescription
POST/v1/skillsCreateSkillCreate a skill
GET/v1/skillsListSkillsList skills
GET/v1/skills/{skill_id}GetSkillGet skill details
DELETE/v1/skills/{skill_id}DeleteSkillDelete a skill
POST/v1/skills/{skill_id}/versionsCreateVersionCreate skill version
GET/v1/skills/{skill_id}/versionsListVersionsList skill versions
GET/v1/skills/{skill_id}/versions/{version}GetVersionGet skill version
DELETE/v1/skills/{skill_id}/versions/{version}DeleteVersionDelete skill version

Request/Response Schema Quick Reference

CreateAgent Request Body

Always start here. model, system, tools, mcp_servers, skills are top-level fields on this object — they do NOT go on the session.

{
  "name": "string (required, 1-256 chars)",
  "model": "{{OPUS_ID}} (required — bare string, or {id, speed} object)",
  "description": "string (optional, up to 2048 chars)",
  "system": "string (optional, up to 100,000 chars)",
  "tools": [
    { "type": "agent_toolset_20260401" }
  ],
  "skills": [
    { "type": "anthropic", "skill_id": "xlsx" },
    { "type": "custom", "skill_id": "skill_abc123", "version": "1" }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "metadata": {
    "key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)"
  }
}

Limits: tools max 50, skills max 64, mcp_servers max 20 (unique names).

CreateSession Request Body

{
  "agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)",
  "environment_id": "env_abc123 (required)",
  "title": "string (optional)",
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/owner/repo (required)",
      "authorization_token": "ghp_... (required)",
      "mount_path": "/workspace/repo (optional — defaults to /workspace/<repo-name>)",
      "checkout": { "type": "branch", "name": "main" }
    }
  ],
  "vault_ids": ["vlt_abc123 (optional — MCP credentials with auto-refresh)"],
  "metadata": {
    "key": "value"
  }
}

The agent field accepts only a string ID or {type: "agent", id, version} — model/system/tools live on the agent, not here.

checkout accepts {type: "branch", name: "..."} or {type: "commit", sha: "..."}. Omit for the repo’s default branch.

CreateEnvironment Request Body

{
  "name": "string (required)",
  "description": "string (optional)",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "unrestricted | limited (union — see SDK types)"
    },
    "packages": { }
  },
  "metadata": { "key": "value" }
}

SendEvents Request Body

{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Hello"
        }
      ]
    }
  ]
}

Tool Result Event

{
  "type": "user.custom_tool_result",
  "custom_tool_use_id": "sevt_abc123",
  "content": [{ "type": "text", "text": "Result data" }],
  "is_error": false
}

Error Handling

Managed 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:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Description of what went wrong"
  },
  "request_id": "req_011CRv1W3XQ8XpFikNYG7RnE"
}

Include 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:

StatusError typeDescription
400invalid_request_errorThe request was malformed or missing required parameters
401authentication_errorInvalid or missing API key
403permission_errorThe API key doesn’t have permission for this operation
404not_found_errorThe requested resource doesn’t exist
409invalid_request_errorThe request conflicts with the resource’s current state (e.g., sending to an archived session)
413request_too_largeThe request body exceeds the maximum allowed size
429rate_limit_errorToo many requests — check rate limit headers for retry timing
500api_errorAn internal server error occurred
529overloaded_errorThe service is temporarily overloaded — retry with backoff

Note 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.

Rate Limits

Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your Messages API token limits. Model inference inside a session still draws from your organization’s standard ITPM/OTPM limits.

Endpoint groupScopeRPMMax concurrent
Create operations (Agents, Sessions, Vaults)organization60—
All other operations (Agents, Sessions, Vaults)organization600—
All operations (Environments)organization605

Files and Skills endpoints use the standard tier-based rate limits.

When a limit is exceeded the API returns 429 with a rate_limit_error (see 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.