Request body

• namestring必填

  Human-readable name for the environment

• metadataobject可选

  User-provided metadata key-value pairs

• configobject可选

  Environment configuration

  ▸ 展开子字段（3）

  • typestring必填

    Self-hosted environment selector; unsupported here and rejected with 400. Use a cloud environment instead.

    取值 self_hosted
  • networkingobject可选

    Network configuration policy. Omit on update to preserve the existing value.

  • packagesobject可选

    Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. Under `limited` networking, requires `networking.allow_package_managers` to be `true`.

• descriptionstring可选

  Optional description of the environment

• scopestring可选

  The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. API organizations support only 'organization'; 'account' is rejected. If not specified, defaults based on organization type.

Returns

200

Supports tenant-owned cloud environments, configuration updates and soft archival; built-ins are read-only. Lists accept limit, page and include_archived. Limited networking applies at sandbox creation; package installation failure terminates the session with ENVIRONMENT_PACKAGE_INSTALL_FAILED. self_hosted, scope and cross-session package caching are not supported.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• environment_idstring必填

  path: Environment id, as returned by environments.create or environments.list. Built-in environments can be read but not changed.

• namestring可选

  Updated name for the environment

• metadataobject可选

  User-provided metadata key-value pairs. Set a value to null or empty string to delete the key.

• configobject可选

  Updated environment configuration

  ▸ 展开子字段（3）

  • typestring必填

    Self-hosted environment selector; unsupported here and rejected with 400. Use a cloud environment instead.

    取值 self_hosted
  • networkingobject可选

    Network configuration policy. Omit on update to preserve the existing value.

  • packagesobject可选

    Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. Under `limited` networking, requires `networking.allow_package_managers` to be `true`.

• descriptionstring可选

  Updated description of the environment. Omit to preserve; null clears to null; an empty string is stored as an empty string.

• scopestring可选

  The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only.

Returns

200

Supports tenant-owned cloud environments, configuration updates and soft archival; built-ins are read-only. Lists accept limit, page and include_archived. Limited networking applies at sandbox creation; package installation failure terminates the session with ENVIRONMENT_PACKAGE_INSTALL_FAILED. self_hosted, scope and cross-session package caching are not supported.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• environment_idstring必填

  path: Environment id, as returned by environments.create or environments.list. Built-in environments can be read but not changed.

Returns

200

Supports tenant-owned cloud environments, configuration updates and soft archival; built-ins are read-only. Lists accept limit, page and include_archived. Limited networking applies at sandbox creation; package installation failure terminates the session with ENVIRONMENT_PACKAGE_INSTALL_FAILED. self_hosted, scope and cross-session package caching are not supported.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request body

• namestring必填

  Name of the entry or object.

• environment_idstring可选

  Environment recipe id; null or omitted when none was selected.

Returns

201

Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• limitinteger可选
  默认 20

  query: Maximum number of items to return in this page: a positive integer, at most 100 (default 20; for session resources default and maximum are 1000). A larger value returns 400.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

Returns

200

Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

Returns

200

Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

• namestring必填

  Name of the entry or object.

Returns

200

Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

Returns

200

Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

Returns

200

Own-face superset: Managed Agents has no persistent Computer deletion lifecycle. Only archived computers can be deleted. Active computers return 400 COMPUTER_ACTIVE (archive first). Destroy storage before removing registration. Success returns id and type=computer_deleted; missing or foreign computers return 404.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

• pathstring可选
  默认 "/"

  query: Directory on the computer to list; absolute path as returned in the path field of an earlier listing. Omit it to list from the computer's root.

Returns

200

Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

• pathstring必填

  query: Absolute path of the file whose content to download, as returned in the path field of computers.files.list.

Returns

200

Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

Returns

200

Own-face extension: Managed Agents has no persistent Computer connection. Returns the public SDK sandbox_id, envd_access_token and template_id. Archived computers remain accessible; foreign or absent computers return 404. Never cache credentials.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• computer_idstring必填

  path: Computer id (cmp_...), as returned by computers.create or computers.list.

• namestring必填

  query: Single filename, at most 255 UTF-8 bytes, excluding slash, dot segments and control characters.

Returns

201

Own-face superset: Managed Agents has no persistent Computer attachment directory. User uploads overwrite the same name; agents retain read-only access. Run-token uploads return 403 READ_ONLY. name is one filename of at most 255 UTF-8 bytes; MIME is inferred from the extension; custom Content-Type is not persisted and digest may be absent. Limit 16 MiB (413); invalid names return 400. Archived computers accept uploads; foreign computers return 404.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• typestring必填

  query: Resource type selector for the body; only file resources are supported. Normally you send type inside the JSON body and omit this parameter.

  取值 file
• file_idstring必填

  ID of a previously uploaded file.

• mount_pathstring可选

  Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.

Returns

200

Supports persistence, retrieval and removal of file resource references, up to 500 per session. Files must be live and owned by the current tenant. Paths default to /mnt/session/uploads/<file_id>; custom paths are rooted there and parent traversal is rejected. File content is immutable through this API. Sandbox synchronization is not implemented in this batch.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

Returns

200

Supports persistence, retrieval and removal of file resource references, up to 500 per session. Files must be live and owned by the current tenant. Paths default to /mnt/session/uploads/<file_id>; custom paths are rooted there and parent traversal is rejected. File content is immutable through this API. Sandbox synchronization is not implemented in this batch.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• resource_idstring必填

  path: Id of a resource attached to the session, as returned by sessions.resources.add or sessions.resources.list.

• session_idstring必填

  query: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

Returns

200

Supports persistence, retrieval and removal of file resource references, up to 500 per session. Files must be live and owned by the current tenant. Paths default to /mnt/session/uploads/<file_id>; custom paths are rooted there and parent traversal is rejected. File content is immutable through this API. Sandbox synchronization is not implemented in this batch.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• resource_idstring必填

  path: Id of a resource attached to the session, as returned by sessions.resources.add or sessions.resources.list.

• session_idstring必填

  query: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

Returns

200

Supports persistence, retrieval and removal of file resource references, up to 500 per session. Files must be live and owned by the current tenant. Paths default to /mnt/session/uploads/<file_id>; custom paths are rooted there and parent traversal is rejected. File content is immutable through this API. Sandbox synchronization is not implemented in this batch.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• created_at[gte]string可选

  query: Return agents created at or after this time (inclusive).

• created_at[lte]string可选

  query: Return agents created at or before this time (inclusive).

• include_archivedboolean可选

  query: Include archived agents in results. Defaults to false.

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

Returns

200

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request body

• namestring必填

  Human-readable agent name, 1-255 characters, unique within the workspace.

• modelstring | object必填

  The model powering the agent: a model name string (e.g. claude-opus-5) or an object for extra configuration (see subfields).

  ▸ 展开子字段（5）

  • idstring必填

    The model name string, e.g. claude-opus-5.

  • effortstring | object可选

    How hard the model works per inference: a bare level string (e.g. high) or a {type: high} object. On create, omitted resolves the per-model default; on update, omitting preserves it.

  • inference_geostring可选

    Geographic region for inference; unset falls through to the workspace default. model is replaced wholesale — omitting the subfield on update clears it.

  • speedstring可选

    Inference speed mode: fast generates output notably quicker at premium pricing. Not all models support it; invalid combinations are rejected at create time.

  • settingsobject可选

    Platform model settings. Only reasoning is supported; other model controls return 400.

• systemstring可选

  The agent's system prompt.

• metadataobject可选

  Custom metadata key-value pairs; up to 16 keys of at most 512 characters each.

• descriptionstring可选

  What the agent does.

• mcp_serversarray可选

  MCP servers the agent connects to; up to 20 with unique names. Every server must be referenced by an mcp_toolset in tools, or the request is rejected.

  ▸ 展开子字段（3）

  • typestring必填

    Server type; only url is supported today.

    取值 url
  • namestring必填

    Name unique within this list, 1-255 characters, referenced by mcp_toolset configurations.

  • urlstring必填

    The MCP server's endpoint URL.

• multiagentobject可选◐ 部分支持

  Multiagent topology: the session's primary thread orchestrates work by spawning session threads drawn from the agents roster.

  ▸ 展开子字段（2）

  • agentsarray必填

    A roster of 1-20 agent IDs, {type: agent, id, version?} references or at most one {type: self}. Versions are pinned on create/update. Members must be distinct, exist, be unarchived and have no multiagent topology. Each coordinator permits at most one advisor whose model must be available and differ from the agent model; only the primary session can consult it, each consultation uses a separate advisor thread, and advice returns via agent.thread_message_received.

  • typestring必填

    Topology type; only coordinator today.

    取值 coordinator
• skillsarray可选

  Skills available to the agent.

• toolsarray可选

  Tool configurations for the agent; up to 128 tools across all toolsets.

• computer_idstring可选

  Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined.

• ▸ 更多参数（2）

  • subagent_modelstring可选

    Own-face extension: revision-pinned default subagent model ID. Omit to preserve; null clears it. Priority: call model, this field, then the roster member model or the parent model for built-ins. Not accepted or returned on the compatibility face.

  • modelsobject可选

    Extension: selectable models, available only on /agent/v1.

    ▸ 展开子字段（1）

    • allowedarray必填

      Must include the default model. Omit on creation to allow only the default; omit on update to preserve the list. Sessions use their pinned version’s list.

Returns

200

agent_toolset_20260401 is the native toolset: bash, edit, glob, grep, read, write, web_search, web_fetch, TaskOutput, TaskStop, Monitor, Agent and SendMessage. New agents enable all tools by default. Configure each tool through name, enabled and permission_policy in configs; omitted tools follow default_config (enabled by default). Background tasks, Monitor and subagents require bash. Enabling any background tool exposes bash run_in_background. The /anthropic compatibility API accepts and returns only the eight official tools, and sessions created there receive only those tools. Supports text prompts, models, metadata and built-in tools. Optional model.settings.reasoning accepts low, medium, high, xhigh or none as the session default. Explicit session thinking takes precedence; unsupported agent defaults fall back to the model default_effort. Example model: {id: "deepseek-v4-flash", settings: {reasoning: "high"}}. Skills and other additional model controls are not supported and return 400. Set up to 100 allow, ask and deny rules in toolset permissions for future conversations. multiagent accepts null or a coordinator roster of 1–20 agent IDs, {type:"agent",id,version?} references or at most one {type:"self"}. Versions are pinned on create/update. Members must be distinct, exist, be unarchived and have no multiagent topology. A roster can enable Agent while bash is enabled; SendMessage follows its tool configuration. Each coordinator permits at most one advisor whose model must be available and differ from the agent model; only the primary session can consult it, each consultation uses a separate advisor thread, and advice returns via agent.thread_message_received. The /agent/v1 top-level subagent_model is a nullable model ID stored in each revision: omit to preserve, null to clear. The model must exist. Priority: call model > subagent_model > roster member model (parent session model for built-ins). /anthropic neither accepts nor returns this field.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• agent_idstring必填

  path: Agent id, as returned by agents.create or agents.list (for a session filter, the agent the session was created with). Not the agent name.

• versionnumber可选

  query: Agent version to read; omit for the latest. Integer of at least 1; versions are listed by agents.versions.list.

Returns

200

tools returns all resolved native tool configurations in one agent_toolset_20260401 entry, ready for an update round trip. Replace example resource IDs with IDs from resources you created.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• agent_idstring必填

  path: Agent id, as returned by agents.create or agents.list (for a session filter, the agent the session was created with). Not the agent name.

• namestring可选

  Agent name; omit to preserve. Cannot be cleared.

• modelstring | object可选

  The model powering the agent: a model name string (e.g. claude-opus-5) or an object for extra configuration (see subfields).

  ▸ 展开子字段（5）

  • idstring必填

    The model name string, e.g. claude-opus-5.

  • effortstring | object可选

    How hard the model works per inference: a bare level string (e.g. high) or a {type: high} object. On create, omitted resolves the per-model default; on update, omitting preserves it.

  • inference_geostring可选

    Geographic region for inference; unset falls through to the workspace default. model is replaced wholesale — omitting the subfield on update clears it.

  • speedstring可选

    Inference speed mode: fast generates output notably quicker at premium pricing. Not all models support it; invalid combinations are rejected at create time.

  • settingsobject可选

    Platform model settings. Only reasoning is supported; other model controls return 400.

• systemstring可选

  System prompt; omit to preserve, send an empty string or null to clear.

• versionnumber可选

  The agent's current version for concurrency control: must match the version returned by the latest create or retrieve, or the call answers a conflict.

• metadataobject可选

  Metadata patch: set a key to a string to upsert it, or to null to delete it; omit the field to preserve. Up to 16 keys of at most 512 characters.

• descriptionstring可选

  Description; omit to preserve, send an empty string or null to clear.

• mcp_serversarray可选

  Full-replacement MCP server list; omit to preserve, send an empty array or null to clear.

• multiagentobject可选◐ 部分支持

  Multiagent topology: the session's primary thread orchestrates work by spawning session threads drawn from the agents roster.

  ▸ 展开子字段（2）

  • agentsarray必填

    A roster of 1-20 agent IDs, {type: agent, id, version?} references or at most one {type: self}. Versions are pinned on create/update. Members must be distinct, exist, be unarchived and have no multiagent topology. Each coordinator permits at most one advisor whose model must be available and differ from the agent model; only the primary session can consult it, each consultation uses a separate advisor thread, and advice returns via agent.thread_message_received.

  • typestring必填

    Topology type; only coordinator today.

    取值 coordinator
• skillsarray可选

  Full-replacement skill list; omit to preserve, send an empty array or null to clear.

• ▸ 更多参数（4）

  • toolsarray可选

    Full-replacement tool configuration; omit to preserve, send an empty array or null to clear.

  • computer_idstring可选

    Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined.

  • subagent_modelstring可选

    Own-face extension: revision-pinned default subagent model ID. Omit to preserve; null clears it. Priority: call model, this field, then the roster member model or the parent model for built-ins. Not accepted or returned on the compatibility face.

  • modelsobject可选

    Extension: selectable models, available only on /agent/v1.

    ▸ 展开子字段（1）

    • allowedarray必填

      Must include the default model. Omit on creation to allow only the default; omit on update to preserve the list. Sessions use their pinned version’s list.

Returns

200

Use agent_toolset_20260401.configs to enable each native tool and set its permission policy. Omitted tools follow default_config; background tasks, Monitor and subagents require bash. Use version for optimistic concurrency; conflicts return 409 and unchanged updates preserve the version. Skills are not supported. Update toolset permissions to save allowed operations in a new agent version for future conversations. multiagent accepts null or a coordinator roster of 1–20 agent IDs, {type:"agent",id,version?} references or at most one {type:"self"}. Versions are pinned on create/update. Members must be distinct, exist, be unarchived and have no multiagent topology. A roster can enable Agent while bash is enabled; SendMessage follows its tool configuration. Each coordinator permits at most one advisor whose model must be available and differ from the agent model; only the primary session can consult it, each consultation uses a separate advisor thread, and advice returns via agent.thread_message_received. The /agent/v1 top-level subagent_model is a nullable model ID stored in each revision: omit to preserve, null to clear. The model must exist. Priority: call model > subagent_model > roster member model (parent session model for built-ins). /anthropic neither accepts nor returns this field.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• agent_idstring必填

  path: Agent id, as returned by agents.create or agents.list (for a session filter, the agent the session was created with). Not the agent name.

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

Returns

200

Replace example resource IDs with IDs from resources you created.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• agent_idstring必填

  path: Agent id, as returned by agents.create or agents.list (for a session filter, the agent the session was created with). Not the agent name.

Returns

200

Archived agents remain readable, including versions, but cannot be updated. Only archive your own test agent.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• agent_idstring可选

  query: Return only sessions created with this agent id (from agents.list or agents.create). This is one of the three filters sessions.list supports.

• agent_versionnumber可选

  query: Filter by agent version; only applies when agent_id is also set.

• created_at[gt]string可选

  query: Exclusive created-at lower bound for sessions. Declared by the Managed Agents shape but not supported here; sending it returns 400.

• created_at[gte]string可选

  query: Created-at lower bound for sessions. Declared by the Managed Agents shape but not supported here: sessions.list honors only limit, page and agent_id, and other filters return 400.

• created_at[lt]string可选

  query: Exclusive created-at upper bound for sessions. Declared by the Managed Agents shape but not supported here; sending it returns 400.

• created_at[lte]string可选

  query: Created-at upper bound for sessions. Declared by the Managed Agents shape but not supported here: sessions.list honors only limit, page and agent_id, and other filters return 400.

• deployment_idstring可选

  query: Declared by the Managed Agents shape but not supported by sessions.list; sending it returns 400.

• include_archivedboolean可选

  query: Declared by the Managed Agents shape but not supported by sessions.list; sending it returns 400. Archived sessions are retrievable by id.

• memory_store_idstring可选

  query: Declared by the Managed Agents shape but not supported by sessions.list; sending it returns 400.

• orderstring可选

  query: Order by creation time: asc oldest first, desc newest first (default).

• ▸ 更多参数（3）

  • statusesarray可选

    query: Filter by session status; repeat the parameter to match several.

  • limitnumber可选

    query: Number of items per page.

  • pagestring可选

    query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

Returns

200

Supports limit, page and agent_id. agent_version, time ranges, deployment_id, memory_store_id, include_archived, order and statuses are not supported and return 400.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request body

• modelstring可选

  The model powering the agent: a model name string (e.g. claude-opus-5) or an object for extra configuration (see subfields).

• agentstring | object必填

  The agent the session runs: an agent ID string (pins the latest version) or an object with id and version (see subfields).

  ▸ 展开子字段（8）

  • idstring必填

    The ID of the agent the session runs.

  • typestring必填

    Reference type; only agent today.

    取值 agent_with_overrides
  • versionnumber可选

    The specific agent version to pin; omit for the latest.

  • mcp_serversarray可选

    Replacement MCP server list for this session: the provided array applies wholesale; an empty array clears, omitting keeps the agent's configuration.

  • modelstring | object可选

    Replacement model for this session: a model name string (e.g. claude-opus-5) or a config object; omit to keep the agent's model.

  • skillsarray可选

    Replacement skill list for this session; an empty array clears, omitting keeps the agent's skills.

  • systemstring可选

    Replacement system prompt for this session, up to 100,000 characters; null clears it, omitting keeps the agent's.

  • toolsarray可选

    Replacement tool configuration for this session; an empty array clears, omitting keeps the agent's.

• environment_idstring可选

  ID of the environment the session runs in; it determines the container's base environment.

• titlestring可选

  Human-readable session title.

• metadataobject可选

  Custom metadata key-value pairs for the session.

• budgetobject可选

  Spending cap for the session.

  ▸ 展开子字段（2）

  • max_list_costobject必填

    Cap on list-call spending within the budget.

  • typestring必填

    Budget type; only max_list_cost today.

    取值 limit
• initial_eventsarray可选

  Initial events sent to the session in order at creation; user.message and user.define_outcome are supported, up to 50.

• resourcesarray可选

  Resources (e.g. repositories, files) to mount into the session's container.

• vault_idsarray可选

  Vault IDs for stored credentials the agent can use during the session.

• cwdstring可选
  默认 "/home/user/workspace"

  Session working directory on any machine. Must be an absolute path within /home/user with no . or .. segments. Repeated and trailing slashes are normalized. Invalid values return 400 invalid_request_error with Invalid cwd.

• ▸ 更多参数（3）

  • computer_idstring可选

    Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined.

  • time_zonestring可选
    默认 "UTC"

    Praxis extension: the session's IANA time zone name (e.g. Asia/Shanghai) — the clock the runtime environment block renders for every turn. Absent means UTC. Only IANA names are accepted; fixed offsets ("+08:00") and unknown names return 400. Never stored in `metadata`.

  • thinkingobject可选

    Praxis extension: explicit session thinking effort; null inherits the pinned agent default, then the model default. none disables thinking only when model.thinking.can_disable is true. Unsupported efforts return 400 invalid_request_error.

    ▸ 展开子字段（1）

    • effortstring必填

      Thinking level for this session. The model must support the chosen effort; none requires can_disable. Null on thinking restores inheritance from the agent and model.

      取值 lowmediumhighxhighnone

Returns

200

Create with optional model (an ID string in models.allowed; only the default if no list) and thinking ({effort: "low|medium|high|xhigh|none"} or null), saved before initial_events execute. Omitted or null thinking inherits the agent default, then the model default. Efforts must be in model.thinking.efforts; none requires can_disable. Invalid selections return 400 invalid_request_error. The response includes thinking and model.thinking: {efforts, can_disable, default_effort}; unknown capability and an unspecified default_effort are null. Example: {"agent":"agent_123", "model":"deepseek-v4-flash","thinking":{"effort":"xhigh"}}. These selection fields belong only to /agent/v1. Create an agent first and replace agent_123 with its returned id. Omit environment_id to get a light machine, unless an explicit or agent-default computer_id selects a Computer. Select node22 or a tenant-owned cloud environment for a sandbox recipe. Responses omit environment_id when no recipe is selected. Inline agent overrides, budgets and vaults are not supported. File resources are persisted, up to 500 per session; sandbox synchronization is not implemented in this batch.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

Returns

200

Replace example resource IDs with IDs from resources you created.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• message_idstring必填

  UI message ID from an own-face event’s message_id field; must identify the last assistant message of a successfully completed turn.

Returns

201

Available only on /agent/v1. Use the message_id field from own-face events, not the event id. Copies every message and part through the target, including tool calls and results. The parent is unchanged; another running turn does not prevent forking an earlier completed turn. The new root session appears in the session list with the same agent version, current model and thinking settings, and cwd working directory. Its title is the parent title plus “ 的分支”. If the parent has a sandbox, the new session owns an independent fork including a memory snapshot. Inherited running tasks are terminated, ring targets are replaced with the new session only, and its background-task table starts empty. Without a parent sandbox, creation remains lazy. Returns 201 with the same Session shape as retrieval. forked_from is {session_id, message_id}, or null for ordinary sessions. Imported history ends with session.forked containing forked_from_session_id and forked_from_message_id. These fields and this event are own-face only. Invalid requests return 400; ineligible targets return 409 FORK_TARGET_INVALID; missing sessions or sessions belonging to another caller return 404. Initialization failures leave the child unpublished and reclaim the forked sandbox.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

Returns

200

Praxis extension available only on /agent/v1, following Claude Agent SDK getContextUsage() with snake_case fields. detail is summary: the latest actual model usage takes precedence, and local estimates apportion source totals; used categories sum to total_tokens. Only nonzero sources appear. Classify rows by kind (used/free/buffer/deferred). key is a stable source identifier extension; clients must tolerate unknown keys and new sources, falling back to name. MCP tools group by server, plugin blocks by id, and compaction summaries are counted separately. excluded_items is currently zero. Before measurement, total_tokens, total_tokens_source and measured_at are null, categories is empty, and details are zero or empty arrays. Model selection recalculates max_tokens, auto_compact_threshold and free/buffer while preserving the latest measurement. is_auto_compact_enabled is false for unknown capacity or a tripped compaction breaker. For example model.thinking is {efforts: [high, xhigh], can_disable: true, default_effort: high}. model.thinking contains efforts, can_disable and nullable default_effort; the entire thinking value is null when capability is unknown. Missing or inaccessible sessions return 404.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

Returns

200

Own-face extension. Returns { data: BackgroundTask[] }. Each task has id, kind, title, thread_id, status, started_at, ended_at, cancellable, notified_at and trigger_count. Subagent rows link to their child thread via thread_id; other kinds have null. kind is an open string; tolerate unknown kinds. Status is running, result_pending, completed, failed, cancelled or lost. Only completed tasks with pending delivery are result_pending. Timestamps are RFC3339; ended_at is null while running. notified_at is the admission time of the latest system notification batch, or null. trigger_count counts admitted monitor event batches, or is null without records and for other kinds. Only supported running tasks without stop intent are cancellable. Missing or inaccessible sessions return 404.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• task_idstring必填

  path: Background task id (task_...), as listed by sessions.background_tasks.list.

• offsetinteger可选
  默认 0

  query: Byte offset into the task output to read from; start at 0 and continue with the next_offset of the previous response. Integer of at least 0, default 0.

• max_bytesinteger可选
  默认 65536

  query: Maximum number of bytes to return: an integer from 1 to 262144, default 65536.

Returns

200

Own-face extension. offset defaults to 0; max_bytes defaults to 65536 and must be between 1 and 262144. Returns text, next_offset and eof. Offsets count UTF-8 bytes, not characters; partial trailing characters are retained for the next read. eof describes the current log, which may grow while running. A paused or missing sandbox returns empty text, the original offset, eof=true and unavailable=true, without waking it. Reading does not acknowledge model result delivery. Missing or inaccessible sessions or tasks return 404; invalid ranges return 400.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• task_idstring必填

  path: Background task id (task_...), as listed by sessions.background_tasks.list.

Returns

200

Own-face extension. No request body is required. Uses the same stop implementation as TaskStop: records stop_requested_at and signals the process group. Returns BackgroundTask with the same fields as the list operation. Until termination is observed, status may remain running with cancellable=false. An ended or unsupported task returns 409. Missing or inaccessible sessions or tasks return 404.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• instructionsstring可选

  Optional focus instructions for the summary, passed to the summarizing model unchanged.

Returns

200

Available only on /agent/v1. The body may be omitted or {}. Optional instructions must be a string and is forwarded unchanged. Idempotency-Key is forwarded unchanged; a UUID is generated when absent. Returns { type: session_compaction, id, status, reason? }, where id is the operation ID. queued/running return 202; skipped/succeeded/failed return 200. Non-string instructions return 400 invalid_request_error. Missing or inaccessible managed sessions return 404 not_found_error.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• operation_idstring必填

  path: Compaction operation id returned by sessions.compact in the id field of the session_compaction object.

Returns

200

Available only on /agent/v1. Returns { type: session_compaction, id, status, reason? } with HTTP 200 for every status. A missing operation or inaccessible session returns 404 not_found_error.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

Returns

200

Available only on /agent/v1. Returns { data: [...] }. Each entry contains type, id, event_id, trigger, status, model, compacted_message_count, input_tokens_before, input_tokens_after, summary, error and created_at, as recorded by the service. Missing or inaccessible managed sessions return 404 not_found_error.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• created_at[gt]string可选

  query: Return events created after this time (exclusive). Compared against the event's `processed_at` value.

• created_at[gte]string可选

  query: Return events created at or after this time (inclusive). Compared against the event's `processed_at` value.

• created_at[lt]string可选

  query: Return events created before this time (exclusive). Compared against the event's `processed_at` value.

• created_at[lte]string可选

  query: Return events created at or before this time (inclusive). Compared against the event's `processed_at` value.

• orderstring可选

  query: Order by processed time: asc chronological (default), desc the reverse.

• typesarray可选

  query: Filter by event type; values match the returned events' type field (e.g. user.message, agent.tool_use). Omit for all types.

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

Returns

200

Send a message before reading history. Until processing finishes, only admitted input may be visible. Pagination, event type and time filters are supported. A session waiting for tool approval pauses on session.status_idle with stop_reason requires_action, whose event_ids list the agent.tool_use events to confirm. A failed run emits session.error before session.status_terminated. agent.thinking carries the thinking text in content. When searching or reading web pages, tool results use official search_result blocks on both API surfaces. Answer text blocks carry citations as an /agent/v1 extension; /anthropic renders answer references as [n] in the text.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• eventsarray必填

  Events to send to the session.

Returns

200

Each user.message accepts exactly one nonempty text block. Replace sesn_123 with your session id. Text user.message, user.interrupt and tool confirmation are supported. To guide a running turn, send a user.steer event with event_id referencing a queued user.message. Current tools continue; the message enters the next model request. The user.steer receipt has its own processed_at; repeated marking returns the same receipt. Processing or withdrawn inputs return 409; missing events return 404. Pending approvals defer injection. If the turn ends first, the input runs normally from the queue. Ordinary messages remain queued by default. This extension is unavailable on /anthropic. The response acknowledges inputs; read replies from event history or the stream. A user.message sent while the session waits for tool approval is queued: the returned event has processed_at null and runs in order once the approval is resolved. When allowing a tool call, copy its permission_suggestions into updated_permissions to remember similar operations for this conversation; dangerous operations offer no suggestions to remember. When searching or reading web pages, tool results use official search_result blocks on both API surfaces. Answer text blocks carry citations as an /agent/v1 extension; /anthropic renders answer references as [n] in the text.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• event_deltasarray可选

  query: When set, this connection also receives streaming deltas (`event_start`, `event_delta`) while an event is being produced, before the event itself arrives. Deltas are best-effort; when the final event is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no final event — its terminal `span.model_request_end` closes the preview. Accepts one or more event types to preview and may be repeated: `agent.message` streams `content_delta` fragments; `agent.thinking` is start-only — a signal that the agent has begun extended thinking, concluded by the `agent.thinking` event itself. Only previews of the requested event types are sent.

Returns

200

Keep the SSE connection open and send a message in another request after replacing sesn_123. Stopping the stream disconnects the subscription, not the agent. SDK 0.124.0 filters session.usage; read history for full usage. Pass event_deltas[]=agent.message or event_deltas[]=agent.thinking to receive incremental previews (event_start and event_delta) before the final event. Pass event_deltas[]=agent.tool_use to receive input_json_delta fragments while tool arguments are being generated. When searching or reading web pages, tool results use official search_result blocks on both API surfaces. Answer text blocks carry citations as an /agent/v1 extension; /anthropic renders answer references as [n] in the text.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• modelstring可选

  Extension: model ID from the session’s pinned version models.allowed, or its default model when no list exists. Applies on the next turn without interrupting the current turn. No context-window check is performed here.

• agentobject可选

  The agent the session runs: an agent ID string (pins the latest version) or an object with id and version (see subfields).

  ▸ 展开子字段（2）

  • mcp_serversarray可选

    Replacement MCP server list for this session: the provided array applies wholesale; an empty array clears, omitting keeps the agent's configuration.

  • toolsarray可选

    Replacement tool configuration for this session; an empty array clears, omitting keeps the agent's.

• titlestring可选

  Human-readable session title.

• metadataobject可选

  Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.

• budgetobject可选

  A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

  ▸ 展开子字段（2）

  • max_list_costobject必填

    Cap on list-call spending within the budget.

  • typestring必填

    Budget type; only max_list_cost today.

    取值 limit
• vault_idsarray可选

  Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.

• thinkingobject可选

  Praxis extension: explicit session thinking effort; null inherits the pinned agent default, then the model default. none disables thinking only when model.thinking.can_disable is true. Unsupported efforts return 400 invalid_request_error.

  ▸ 展开子字段（1）

  • effortstring必填

    Thinking level for this session. The model must support the chosen effort; none requires can_disable. Null on thinking restores inheritance from the agent and model.

    取值 lowmediumhighxhighnone

Returns

200

Optional model is an ID in the pinned version allowed list; thinking is {effort: "low|medium|high|xhigh|none"} or null. Omission preserves the selection; null restores inheritance. A model-only change clears unsupported session thinking. Combined updates validate against the new model; invalid choices return 400 and preserve the previous selection. Changes affect the next turn, not an in-flight turn. Example: {"model":"deepseek-v4-flash","thinking":{"effort":"xhigh"}}. Responses include thinking and model.thinking: {efforts, can_disable, default_effort}; unknown capability is null. These fields are available only on /agent/v1. Supports title and metadata with the official patch semantics: a string value upserts the key, null deletes it, a whole-null object clears the bag, and untouched keys are preserved. The official agent override (tools/mcp_servers), budget and vault_ids are not supported and return 400 naming the field. Updating an archived session returns 409.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

Returns

200

Archived sessions refuse new messages with 400 invalid_request_error naming the archived session; retrieval and event history stay readable. Re-archiving is idempotent and archived_at keeps the first archive time.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• limitnumber可选

  query: Number of items per page.

• pagestring可选

  query: Opaque pagination cursor: pass the next_page value of the previous response unchanged. Omit it for the first page. A cursor from a different query or a malformed one returns 400.

Returns

200

Returns the primary thread and every child thread in created_at order. Thread ids use sthr_ plus the owning session suffix; children reference the primary parent_thread_id and retain the parent session_id. agent describes the actual running definition; built-in types use their type name and null for unregistered id/version. Archived children have status terminated and archived_at. stats/usage remain null without thread-level tracking.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Request parameters

• session_idstring必填

  path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

• thread_idstring必填

  path: Execution thread id (sthr_...), as listed by sessions.threads.list; the primary thread id equals the session's own thread. Unknown or foreign ids return 404.

• session_idstring必填

  query: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.

Returns

200

Returns a primary or child thread belonging to this session, field-for-field identical to its list item. Foreign, unknown and malformed thread ids uniformly return 404 without revealing existence.

Errors follow the Anthropic error format (type / message / request_id) — see error codes