Request body

• modelstring必填◐ Partially supported

  Body param: The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  deepseek-v4-pro, glm-5.3-flash, qwen3.8-flash and claude-opus-5 can be called; deepseek-v4-flash returns 400 on this face.

• max_tokensnumber必填

  Body param: The maximum number of tokens to generate before stopping. Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response. Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.

  Limits output tokens, including reasoning.

• messagesarray必填◐ Partially supported

  Body param: Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{ "role": "user", "content": "Hello, Claude" }] ``` Example with multiple conversational turns: ```json [ { "role": "user", "content": "Hello there." }, { "role": "assistant", "content": "Hi, I'm Claude. How can I help you?" }, { "role": "user", "content": "Can you explain LLMs in plain English?" } ] ``` Example with a partially-filled response from Claude: ```json [ { "role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun" }, { "role": "assistant", "content": "The best answer is (" } ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json { "role": "user", "content": "Hello, Claude" } ``` ```json { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] } ``` See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request.

  Text and tool round trips work. Managed document file_id returns 400; qwen3.8-flash can read inline PDFs. Images have model-specific size limits.

  ▸ 展开子字段（2）

  • contentstring | array必填

    Message content: a plain string (shorthand for one text block) or an array of content blocks such as text, image, document, tool_use and tool_result.

  • rolestring必填

    Who produced the message. Use user for your turns and assistant to replay earlier model turns; system-role messages are accepted by the shape but system instructions normally go in the top-level system field.

• streamboolean可选◐ Partially supported

  Body param: Whether to incrementally stream the response using server-sent events. See [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) for details.

  Content and tool streaming work; extra message_delta events may precede content and message_start usage is zero.

• systemstring | array可选

  Body param: System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).

  Verified to take effect.

• temperaturenumber可选
• top_pnumber可选
• top_knumber可选
• stop_sequencesarray可选◐ Partially supported

  Body param: Custom text sequences that will cause the model to stop generating. Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence.

  Works on deepseek-v4-pro and qwen3.8-flash; glm-5.3-flash truncates text but does not report accurate stop_reason/stop_sequence.

• toolsarray可选

  Body param: Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: - `name`: Name of the tool. - `description`: Optional, but strongly-recommended description of the tool. - `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.

  Verified to take effect.

• ▸ 更多参数（16）

  • tool_choiceobject可选◐ Partially supported

    Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.

    All four modes work on qwen3.8-flash; deepseek-v4-pro ignores any/tool/none and glm-5.3-flash ignores none.

    ▸ 展开子字段（3）

    • typestring必填
      取值 none
    • disable_parallel_tool_useboolean可选○ Currently ignored

      Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use.

      Accepted but currently has no effect. true may still return multiple tool calls.

    • namestring必填

      The name of the tool to use.

  • metadataobject可选◐ Partially supported

    Body param: An object describing metadata about the request.

    Accepts metadata; metadata.user_id is carried on same-protocol lines without promising an upstream echo.

    ▸ 展开子字段（1）

    • user_idstring可选

      An external identifier for the user who is associated with the request. This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.

  • cache_controlobject可选◐ Partially supported

    Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

    Implicit cache hits occur on deepseek-v4-pro, qwen3.8-flash and glm-5.3-flash, but do not establish that the marker controls caching. No hits were observed on claude-opus-5, and ttl=1h had no observed effect.

    ▸ 展开子字段（2）

    • typestring必填

      Always `ephemeral`. Discriminator that marks this object as a CacheControlEphemeral in a `type`-tagged union.

      取值 ephemeral
    • ttlstring可选

      The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.

  • containerstring | object可选○ Currently ignored

    Accepted and ignored; the platform does not implement container.

    ▸ 展开子字段（2）

    • idstring可选

      Container id

    • skillsarray可选

      List of skills to load in the container

  • inference_geostring可选○ Currently ignored

    Accepted and ignored; the platform does not implement inference_geo.

  • output_configobject可选

    Body param: Configuration options for the model's output, such as the output format.

    ▸ 展开子字段（2）

    • effortstring可选◐ Partially supported

      All possible effort levels.

      Only high/xhigh work on deepseek-v4-pro; other levels return 400. All levels return 400 on qwen3.8-flash. glm-5.3-flash accepts levels but usage is not monotonic.

    • formatobject可选◐ Partially supported

      A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

      json_schema works on deepseek-v4-pro and qwen3.8-flash; glm-5.3-flash returns 400 when combined with thinking.

  • service_tierstring可选○ Currently ignored

    Accepted and ignored; the platform does not implement service_tier.

  • thinkingobject可选◐ Partially supported

    Body param: Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

    disabled works on deepseek-v4-pro and qwen3.8-flash; any thinking parameter returns 400 on glm-5.3-flash. adaptive also returns 400 on tested deepseek-v4-pro and qwen3.8-flash.

    ▸ 展开子字段（3）

    • budget_tokensnumber必填◐ Partially supported

      Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

      Accepted on deepseek-v4-pro and qwen3.8-flash but is not a reliable upper bound; glm-5.3-flash returns 400.

    • typestring必填
      取值 adaptive
    • displaystring可选○ Currently ignored

      Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.

      Accepted but currently has no effect. omitted still returns the full thinking content.

  • context_managementobject可选○ Currently ignored

    Accepted and ignored; the platform does not implement context_management.

  • diagnosticsobject可选○ Currently ignored

    Accepted and ignored; the platform does not implement diagnostics.

  • mcp_serversarray可选○ Currently ignored

    Accepted and ignored; the platform does not implement mcp_servers.

  • speedstring可选○ Currently ignored

    Accepted and ignored; the platform does not implement speed.

  • output_formatobject可选○ Currently ignored

    Accepted and ignored legacy field; use output_config.format for structured output.

  • compactionobject可选○ Unsupported

    Recognized compaction; not implemented, and returns 400 explicitly stating that the parameter is not supported.

  • fallback_credit_tokenstring可选○ Unsupported

    Recognized fallback_credit_token; not implemented, and returns 400 explicitly stating that the parameter is not supported.

  • fallbacksstring可选○ Unsupported

    Recognized fallbacks; not implemented, and returns 400 explicitly stating that the parameter is not supported.

Returns

200

With stream=true the reply streams as server-sent events (text/event-stream).

Preserves top-level cache_control, top_k, metadata.user_id, output_config.format, thinking.display and anthropic-user-profile-id. Native-only options restrict routing; requests fail when no provider can preserve them. Nonempty anthropic-workspace-id returns 400. container, inference_geo and service_tier are accepted and ignored; see field support for other extensions. Unknown top-level fields are forwarded unchanged to same-protocol upstream providers, which decide whether to accept them. Declared fields still undergo type and range validation; invalid values return 400 naming the field.

Errors follow the Anthropic format — see error codes

Request body

• modelstring必填

  Body param: The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

  Required and checked for existence; selects native lines and local tokenizers.

• messagesarray必填◐ Partially supported

  Body param: Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{ "role": "user", "content": "Hello, Claude" }] ``` Example with multiple conversational turns: ```json [ { "role": "user", "content": "Hello there." }, { "role": "assistant", "content": "Hi, I'm Claude. How can I help you?" }, { "role": "user", "content": "Can you explain LLMs in plain English?" } ] ``` Example with a partially-filled response from Claude: ```json [ { "role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun" }, { "role": "assistant", "content": "The best answer is (" } ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json { "role": "user", "content": "Hello, Claude" } ``` ```json { "role": "user", "content": [{ "type": "text", "text": "Hello, Claude" }] } ``` See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request.

  Native counting preserves messages. Local counting uses o200k or family-calibrated estimates; images use known model rules or approximate allowances for unknown dimensions. Image URLs are not downloaded.

  ▸ 展开子字段（2）

  • contentstring | array必填

    Message content: a plain string (shorthand for one text block) or an array of content blocks such as text, image, document, tool_use and tool_result.

  • rolestring必填

    Who produced the message. Use user for your turns and assistant to replay earlier model turns; system-role messages are accepted by the shape but system instructions normally go in the top-level system field.

• systemstring | array可选◐ Partially supported

  Body param: System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).

  Forwarded natively; included in local estimates.

• toolsarray可选◐ Partially supported

  Body param: Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: - `name`: Name of the tool. - `description`: Optional, but strongly-recommended description of the tool. - `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.

  Forwarded natively; local estimates include definitions and framing.

• tool_choiceobject可选◐ Partially supported

  Body param: How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.

  Forwarded natively; included in local estimates.

  ▸ 展开子字段（3）

  • typestring必填

    Disable tool calls for this request.

    取值 none
  • disable_parallel_tool_useboolean可选

    Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use.

  • namestring必填

    The name of the tool to use.

• cache_controlobject可选◐ Partially supported

  Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

  Native counting preserves message cache markers; counts do not predict cache hits or billing.

  ▸ 展开子字段（2）

  • typestring必填

    Always `ephemeral`. Discriminator that marks this object as a CacheControlEphemeral in a `type`-tagged union.

    取值 ephemeral
  • ttlstring可选

    The time-to-live for the cache control breakpoint. This may be one the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.

• output_configobject可选◐ Partially supported

  Body param: Configuration options for the model's output, such as the output format.

  Forwarded natively; additional template tokens are not exact locally.

  ▸ 展开子字段（2）

  • effortstring可选

    All possible effort levels.

  • formatobject可选

    A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)

• thinkingobject可选◐ Partially supported

  Body param: Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

  Forwarded natively; local counting does not promise exact thinking-template accounting.

  ▸ 展开子字段（3）

  • budget_tokensnumber必填

    Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`. See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.

  • typestring必填

    Let the model choose its reasoning budget, subject to output_config.effort when supplied.

    取值 adaptive
  • displaystring可选

    Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.

Returns

200

Returns a model-family-calibrated estimate, including Chinese text and tool definitions, with the response header x-praxis-token-count: estimated. Do not use it as an exact usage or billing count.

Errors follow the Anthropic format — see error codes

Request parameters

• limitnumber可选

  query: Number of items per page.

  Verified to take effect.

• before_idstring可选

  query:

  Verified to take effect.

• after_idstring可选

  query:

  Verified to take effect.

Returns

200

Always returns capabilities, max_input_tokens and max_tokens; unknown catalog facts are null. The total context window is not substituted for an independent input limit. Nonempty anthropic-workspace-id returns 400; anthropic-beta version selection is not implemented.

Errors follow the Anthropic format — see error codes

Request body

• filestring必填◐ Partially supported

  Body param: The file to upload. Only the final path component of the part's `filename` is kept; an absent or empty `filename` is replaced with `unnamed` plus the extension for the file's stored `mime_type`, when known.

  Text, PDF and PNG uploads are accepted. Types are detected from content; arbitrary binary data is not supported.

• expires_in_secondsnumber可选◐ Partially supported

  Body param: Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days).

  The form field supports 3600–7776000 seconds; as a query parameter it returns 400 asking you to send it in the form.

Returns

200

SDK 0.128.0 sends form file and optional form expires_in_seconds (3600–7776000 seconds). Any other form field, including purpose, returns 400 invalid_request_error such as "purpose: Extra inputs are not permitted". The only accepted query parameter is the SDK's beta; other query parameters return 400, and a query expires_in_seconds is told to move into the form. Uploads are stored as user_data. anthropic-workspace-id is not supported and returns 400.

Errors follow the Anthropic format — see error codes

Request parameters

• idsarray可选

  query: Query param: Restrict the result set to Files whose `id` is in this list. At most 100 entries (after de-duplication). Mutually exclusive with `page` and `limit`. When supplied, the response is always a single page (`next_page` is null). IDs that do not resolve to a visible File — including deleted Files — are silently omitted.

  Verified to take effect.

• scope_idstring可选◐ Partially supported

  query: Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID).

  Requires anthropic-beta: managed-agents-2026-04-01. Invalid scope_id returns 400; a nonexistent session scope returns 404.

• limitnumber可选

  query: Number of items per page.

  Verified to take effect.

• pagestring可选

  query:

  Verified to take effect.

• after_idstring可选

  query: Return the page of files immediately after this file id (older files).

  Returns the page after this file (older files); cannot be combined with before_id or page.

• before_idstring可选

  query: Return the page of files immediately before this file id (newer files).

  Returns the page before this file (newer files); cannot be combined with after_id or page.

Returns

200

Newest first. Paginate with after_id / before_id and limit (sending both returns 400), or with the page cursor (next_page); use only one of the three. Responses contain data, has_more, first_id, last_id and next_page. ids (up to 100 distinct IDs) is mutually exclusive with page, after_id, before_id and limit. scope_id requires the anthropic-beta: managed-agents-2026-04-01 header; a missing header returns 400 and a nonexistent session scope returns 404. anthropic-workspace-id returns 400.

Errors follow the Anthropic format — see error codes

Request parameters

• file_idstring必填

  path:

Returns

200

Errors follow the Anthropic format — see error codes

Request parameters

• file_idstring必填

  path:

Returns

200

Errors follow the Anthropic format — see error codes

Request parameters

• file_idstring必填

  path:

Returns

400

Only files produced by the code execution tool can be downloaded; downloading a file you uploaded yourself (purpose user_data) returns 400 invalid_request_error, the same as Anthropic's own API.

Errors follow the Anthropic format — 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).

  ▸ 展开子字段（4）

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

• systemstring可选

  The agent's system prompt.

• 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）

  • namestring必填

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

  • typestring必填

    Server type; only url is supported today.

    取值 url
  • urlstring必填

    The MCP server's endpoint URL.

• metadataobject可选

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

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

Returns

200

Supports text prompts, models, metadata and built-in tools. MCP, skills and additional model controls are not supported and return 400. 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. The compatibility API provides only the eight official tools: bash, edit, glob, grep, read, write, web_search and web_fetch. configs rejects other tool names. Sessions created here do not provide background tasks, Monitor or subagents. Use /agent/v1 for all native tools. 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.

Errors follow the Claude Managed Agents format — see error codes

Request parameters

• created_at[gte]string可选

  query: Return records created at or after this time.

• created_at[lte]string可选

  query: Return records created at or before this time.

• include_archivedboolean可选

  query: Whether to include archived records.

• limitnumber可选

  query: Maximum number of items per page.

• pagestring可选

  query: Pagination cursor taken from the previous response's next_page.

Returns

200

Errors follow the Claude Managed Agents format — see error codes

Request parameters

• agent_idstring必填

  path: Filter results by agent ID.

• versionnumber可选

  query: Path parameter: the version.

Returns

200

Replace example resource IDs with IDs from resources you created.

Errors follow the Claude Managed Agents format — see error codes

Request parameters

• agent_idstring必填

  path: Filter results by agent ID.

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

  ▸ 展开子字段（4）

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

• systemstring可选

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

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

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

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

• toolsarray可选

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

• ▸ 更多参数（1）

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

Returns

200

Use version for optimistic concurrency; conflicts return 409 and unchanged updates preserve the version. MCP and skills are not supported. 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. The compatibility API provides only the eight official tools: bash, edit, glob, grep, read, write, web_search and web_fetch. configs rejects other tool names. Sessions created here do not provide background tasks, Monitor or subagents. Use /agent/v1 for all native tools. 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.

Errors follow the Claude Managed Agents format — see error codes

Request parameters

• agent_idstring必填

  path: Filter results by agent ID.

• limitnumber可选

  query: Maximum number of items per page.

• pagestring可选

  query: Pagination cursor taken from the previous response's next_page.

Returns

200

Replace example resource IDs with IDs from resources you created.

Errors follow the Claude Managed Agents format — see error codes

Request parameters

• agent_idstring必填

  path: Filter results by agent ID.

Returns

200

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

Errors follow the Claude Managed Agents format — see error codes

Request body

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

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

• metadataobject可选

  Custom metadata key-value pairs for the session.

• resourcesarray可选◐ 部分支持

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

• titlestring可选

  Human-readable session title.

• vault_idsarray可选○ 未支持

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

Returns

200

Create an agent first and replace agent_123 with its returned id. environment_id is required on this compatibility surface: use node22 or a tenant-owned cloud environment. The native /agent/v1 surface allows omission to select a light machine. Inline agent overrides, budgets and vaults are not supported. 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 Claude Managed Agents format — see error codes

Request parameters

• agent_idstring可选

  query: Filter results by agent ID.

• agent_versionnumber可选

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

• created_at[gt]string可选

  query: Return records created strictly after this time.

• created_at[gte]string可选

  query: Return records created at or after this time.

• created_at[lt]string可选

  query: Return records created strictly before this time.

• created_at[lte]string可选

  query: Return records created at or before this time.

• deployment_idstring可选

  query: Deployment ID (path or query parameter).

• include_archivedboolean可选

  query: Whether to include archived records.

• memory_store_idstring可选

  query: Memory store ID (path or query parameter).

• 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: Maximum number of items per page.

  • pagestring可选

    query: Pagination cursor taken from the previous response's next_page.

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 Claude Managed Agents format — see error codes

Request parameters

• session_idstring必填

  path: Session ID (path or query parameter).

Returns

200

Replace example resource IDs with IDs from resources you created.

Errors follow the Claude Managed Agents format — see error codes

Request parameters

• session_idstring必填

  path: Session ID (path or query parameter).

• 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; other input variants are not. 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.

Errors follow the Claude Managed Agents format — see error codes

Request parameters

• session_idstring必填

  path: Session ID (path or query parameter).

• created_at[gt]string可选

  query: Return records created strictly after this time.

• created_at[gte]string可选

  query: Return records created at or after this time.

• created_at[lt]string可选

  query: Return records created strictly before this time.

• created_at[lte]string可选

  query: Return records created at or before this time.

• 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: Maximum number of items per page.

• pagestring可选

  query: Pagination cursor taken from the previous response's next_page.

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. As in the official API, agent.thinking is a progress signal without content.

Errors follow the Claude Managed Agents format — see error codes

Request parameters

• session_idstring必填

  path: Session ID (path or query parameter).

• event_deltasarray可选

  query: When set, the connection also receives streaming delta events.

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 to receive incremental text previews before the final event; as in the official API, agent.thinking previews are start-only.

Errors follow the Claude Managed Agents format — see error codes

Request parameters

• include_archivedboolean可选

  query: Whether to include archived records.

• limitnumber可选

  query: Maximum number of items per page.

• pagestring可选

  query: Pagination cursor taken from the previous response's next_page.

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 Claude Managed Agents format — see error codes

Request body

• namestring必填

  Human-readable name for the environment

• configobject可选

  Environment configuration

  ▸ 展开子字段（3）

  • typestring必填

    Environment type

    取值 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

• metadataobject可选

  User-provided metadata key-value pairs

• 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

501

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 Claude Managed Agents format — see error codes

Request parameters

• environment_idstring必填

  path: Environment ID (path or query parameter).

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 Claude Managed Agents format — see error codes

Request parameters

• environment_idstring必填

  path: Environment ID (path or query parameter).

• namestring可选

  Updated name for the environment

• configobject可选

  Updated environment configuration

  ▸ 展开子字段（3）

  • typestring必填

    Environment type

    取值 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.

• metadataobject可选

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

• scopestring可选

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

Returns

501

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 Claude Managed Agents format — see error codes

Request parameters

• environment_idstring必填

  path: Environment ID (path or query parameter).

Returns

501

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 Claude Managed Agents format — see error codes