One change
Create Session
api/beta/sessions/create
Nearest release: v2.1.245, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
api/beta/sessions/create Changed · +267 / -334 lines
# Create Session ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create Session ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
The two sides of this change are too far apart to line up, so this is the differ's own diff of it.
from line 1
---- -title: Create Session -url: https://platform.claude.com/docs/en/api/beta/sessions/create ---- - -## Create Session - -**post** `/v1/sessions` +# Create Session + +**POST** `/v1/sessions` Create Session -### Header Parameters +## Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 82
- `"mid-conversation-tool-changes-2026-07-01"` -### Body Parameters +## Body parameters - `agent: string or BetaManagedAgentsAgentParams or BetaManagedAgentsAgentWithOverridesParams`
from line 90
- `string` - - `BetaManagedAgentsAgentParams object { id, type, version }` + - `BetaManagedAgentsAgentParams object` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
from line 98
The `agent` ID. + minLength: 1, maxLength: 128 + - `type: "agent"` - - `"agent"` - - `version: optional number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. - - `BetaManagedAgentsAgentWithOverridesParams object { id, type, mcp_servers, 5 more }` + format: int32 + + - `BetaManagedAgentsAgentWithOverridesParams object` Reference to an `agent` plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged.
from line 116
The `agent` ID. + minLength: 1, maxLength: 128 + - `type: "agent_with_overrides"` - - `"agent_with_overrides"` - - `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams` Replacement MCP server list. Full replacement: the provided array becomes the MCP servers. Send an empty array to clear; omit to preserve the agent's servers.
from line 128
Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. + minLength: 1, maxLength: 255 + - `type: "url"` - - `"url"` - - `url: string` Endpoint URL for the MCP server. + maxLength: 2048 + - `model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams` Replacement model. Accepts the model string, e.g. `claude-opus-5`, or a `model_config` object. Omit to use the agent's model.
from line 208
- `string` - - `BetaManagedAgentsModelConfigParams object { id, effort, inference_geo, speed }` + - `BetaManagedAgentsModelConfigParams object` An object that defines additional configuration control over model use
from line 236
- `"max"` - - `BetaManagedAgentsEffortLow object { type }` + - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - - `"low"` - - - `BetaManagedAgentsEffortMedium object { type }` + - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - - `"medium"` - - - `BetaManagedAgentsEffortHigh object { type }` + - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - - `"high"` - - - `BetaManagedAgentsEffortXhigh object { type }` + - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - - `"xhigh"` - - - `BetaManagedAgentsEffortMax object { type }` + - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - - `"max"` - - `inference_geo: optional string or null` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it.
from line 282
Replacement skill list. Full replacement: the provided array becomes the skills. Send an empty array to clear; omit to preserve the agent's skills. - - `BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }` + - `BetaManagedAgentsAnthropicSkillParams object` An Anthropic-managed skill.
from line 290
Identifier of the Anthropic skill (e.g., "xlsx"). + minLength: 1, maxLength: 64 + - `type: "anthropic"` - - `"anthropic"` - - `version: optional string or null` Version to pin. Defaults to latest if omitted. - - `BetaManagedAgentsCustomSkillParams object { skill_id, type, version }` + minLength: 1, maxLength: 64 + + - `BetaManagedAgentsCustomSkillParams object` A user-created custom skill.
from line 308
Tagged ID of the custom skill (e.g., "skill_01XJ5..."). + minLength: 1, maxLength: 64 + - `type: "custom"` - - `"custom"` - - `version: optional string or null` Version to pin. Defaults to latest if omitted. + minLength: 1, maxLength: 64 + - `system: optional string or null` Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it. + maxLength: 100000 + - `tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams` Replacement tool list. Full replacement: the provided array becomes the tool configuration. Send an empty array to clear; omit to preserve the agent's tools. - - `BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }` + - `BetaManagedAgentsAgentToolset20260401Params object` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - - `"agent_toolset_20260401"` - - `configs: optional array of BetaManagedAgentsAgentToolConfigParams` Per-tool configuration overrides. - - `BetaManagedAgentsBashToolConfigParams object { name, enabled, permission_policy, type }` + - `BetaManagedAgentsBashToolConfigParams object` Configuration override for the bash tool.
from line 346
Must be "bash". - - `"bash"` - - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 354
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - - `"always_allow"` - - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - - `"always_ask"` - - `type: optional "bash"` - - `"bash"` - - - `BetaManagedAgentsEditToolConfigParams object { name, enabled, permission_policy, type }` + - `BetaManagedAgentsEditToolConfigParams object` Configuration override for the edit tool.
from line 376
Must be "edit". - - `"edit"` - - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 384
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: optional "edit"` - - `"edit"` - - - `BetaManagedAgentsReadToolConfigParams object { name, enabled, permission_policy, type }` + - `BetaManagedAgentsReadToolConfigParams object` Configuration override for the read tool.
from line 402
Must be "read". - - `"read"` - - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 410
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: optional "read"` - - `"read"` - - - `BetaManagedAgentsWriteToolConfigParams object { name, enabled, permission_policy, type }` + - `BetaManagedAgentsWriteToolConfigParams object` Configuration override for the write tool.
from line 428
Must be "write". - - `"write"` - - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 436
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: optional "write"` - - `"write"` - - - `BetaManagedAgentsGlobToolConfigParams object { name, enabled, permission_policy, type }` + - `BetaManagedAgentsGlobToolConfigParams object` Configuration override for the glob tool.
from line 454
Must be "glob". - - `"glob"` - - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 462
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: optional "glob"` - - `"glob"` - - - `BetaManagedAgentsGrepToolConfigParams object { name, enabled, permission_policy, type }` + - `BetaManagedAgentsGrepToolConfigParams object` Configuration override for the grep tool.
from line 480
Must be "grep". - - `"grep"` - - `enabled: optional boolean or null` Whether this tool is enabled and available to Claude. Overrides the default_config setting.
from line 488
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: optional "grep"` - - `"grep"` - - - `BetaManagedAgentsWebFetchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }` + - `BetaManagedAgentsWebFetchToolConfigParams object` Configuration override for the web_fetch tool.
from line 506
Must be "web_fetch". - - `"web_fetch"` - - `allowed_domains: optional array of string` Only fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 522
Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs. + format: int32 + - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: optional "web_fetch"` - - `"web_fetch"` - - - `BetaManagedAgentsWebSearchToolConfigParams object { name, allowed_domains, blocked_domains, 4 more }` + - `BetaManagedAgentsWebSearchToolConfigParams object` Configuration override for the web_search tool.
from line 546
Must be "web_search". - - `"web_search"` - - `allowed_domains: optional array of string` Only return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
from line 562
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: optional "web_search"` - - `"web_search"` - - `user_location: optional BetaManagedAgentsUserLocation or null` Approximate user location for search result localization.
from line 580
Location precision. Only "approximate" is supported. - - `"approximate"` - - `city: optional string or null` City name. + minLength: 1, maxLength: 255 + - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase.
from line 594
Region or state name. + minLength: 1, maxLength: 255 + - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". + minLength: 1, maxLength: 255 + - `default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or null` Default configuration for all tools in a toolset.
from line 614
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - - `BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }` + - `BetaManagedAgentsMCPToolsetParams object` Configuration for tools from an MCP server defined in `mcp_servers`.
from line 630
Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. + minLength: 1, maxLength: 255 + - `type: "mcp_toolset"` - - `"mcp_toolset"` - - `configs: optional array of BetaManagedAgentsMCPToolConfigParams` Per-tool configuration overrides.
from line 642
Name of the MCP tool to configure. 1-128 characters. + minLength: 1, maxLength: 128 + - `enabled: optional boolean or null` Whether this tool is enabled. Overrides the `default_config` setting.
from line 652
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution.
from line 672
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - - `BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }` + - `BetaManagedAgentsCustomToolParams object` A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.
from line 688
Description of what the tool does, shown to the agent to help it decide when to use the tool. + minLength: 1 + - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `type: "object"` - - `"object"` - - `properties: optional map[unknown] or null` - `required: optional array of string or null`
from line 704
Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. + minLength: 1, maxLength: 128 + - `type: "custom"` - - `"custom"` - - `version: optional number` The specific `agent` version to use. Omit to use the latest version. + format: int32 + - `environment_id: string` ID of the `environment` defining the container configuration for this session. + minLength: 1, maxLength: 128 + - `budget: optional BetaManagedAgentsBudgetLimit` A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 736
Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - - `"USD"` - - `type: "limit"` - - `"limit"` - - `initial_events: optional array of BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParams` Initial events to send to the `session` at creation, processed in order. Supports `user.message` and `user.define_outcome` events. Maximum 50 events. - - `BetaManagedAgentsUserMessageEventParams object { content, type }` + - `BetaManagedAgentsUserMessageEventParams object` Parameters for sending a user message to the session.
from line 750
Array of content blocks for the user message. - - `BetaManagedAgentsTextBlock object { text, type }` + - `BetaManagedAgentsTextBlock object` Regular text content.
from line 758
The text content. + minLength: 1 + - `type: "text"` - - `"text"` - - - `BetaManagedAgentsImageBlock object { source, type }` + - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL.
from line 770
Union type for image source variants. - - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }` + - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data.
from line 778
Base64-encoded image data. + minLength: 1 + - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + minLength: 1 + - `type: "base64"` - - `"base64"` - - - `BetaManagedAgentsURLImageSource object { type, url }` + - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - - `"url"` - - `url: string` URL of the image to fetch. - - `BetaManagedAgentsFileImageSource object { file_id, type }` + minLength: 1 + + - `BetaManagedAgentsFileImageSource object` Image referenced by file ID.
from line 808
ID of a previously uploaded file. + minLength: 1 + - `type: "file"` - - `"file"` - - `type: "image"` - - `"image"` - - - `BetaManagedAgentsDocumentBlock object { source, type, context, title }` + - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL.
from line 822
Union type for document source variants. - - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }` + - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data.
from line 830
Base64-encoded document data. + minLength: 1 + - `media_type: string` MIME type of the document (e.g., "application/pdf"). + minLength: 1 + - `type: "base64"` - - `"base64"` - - - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }` + - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content.
from line 848
The plain text content. + minLength: 1 + - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - - `"text/plain"` - - `type: "text"` - - `"text"` - - - `BetaManagedAgentsURLDocumentSource object { type, url }` + - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - - `"url"` - - `url: string` URL of the document to fetch. - - `BetaManagedAgentsFileDocumentSource object { file_id, type }` + minLength: 1 + + - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID.
from line 876
ID of a previously uploaded file. + minLength: 1 + - `type: "file"` - - `"file"` - - `type: "document"` - - `"document"` - - `context: optional string or null` Additional context about the document for the model.
from line 890
The title of the document. - - `BetaManagedAgentsRedactedBlock object { type }` + - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - - `"redacted"` - - `type: "user.message"` - - `"user.message"` - - - `BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }` + - `BetaManagedAgentsUserDefineOutcomeEventParams object` Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
from line 910
Rubric for grading the quality of an outcome. - - `BetaManagedAgentsFileRubricParams object { file_id, type }` + - `BetaManagedAgentsFileRubricParams object` Rubric referenced by a file uploaded via the Files API.
from line 920
- `type: "file"` - - `"file"` - - - `BetaManagedAgentsTextRubricParams object { content, type }` + - `BetaManagedAgentsTextRubricParams object` Rubric content provided inline as text.
from line 928
Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters. + maxLength: 262144 + - `type: "text"` - - `"text"` - - `type: "user.define_outcome"` - - `"user.define_outcome"` - - `max_iterations: optional number or null` Eval→revision cycles before giving up. Default 3, max 20. + format: int32 + - `metadata: optional map[string]` Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
from line 948
Resources (e.g. repositories, files) to mount into the session's container. - - `BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }` + - `BetaManagedAgentsGitHubRepositoryResourceParams object` Mount a GitHub repository into the session's container.
from line 956
GitHub authorization token used to clone the repository. + minLength: 1, maxLength: 4096 + - `type: "github_repository"` - - `"github_repository"` - - `url: string` Github URL of the repository + minLength: 1, maxLength: 2048 + - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` Branch or commit to check out. Defaults to the repository's default branch. - - `BetaManagedAgentsBranchCheckout object { name, type }` + - `BetaManagedAgentsBranchCheckout object` - `name: string` Branch name to check out. + minLength: 1, maxLength: 255 + - `type: "branch"` - - `"branch"` - - - `BetaManagedAgentsCommitCheckout object { sha, type }` + - `BetaManagedAgentsCommitCheckout object` - `sha: string` Full commit SHA to check out. + minLength: 7, maxLength: 64 + - `type: "commit"` - - `"commit"` - - `mount_path: optional string or null` Mount path in the container. Defaults to `/workspace/<repo-name>`. - - `BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }` + minLength: 1, maxLength: 4096 + + - `BetaManagedAgentsFileResourceParams object` Mount a file uploaded via the Files API into the session.
from line 1004
ID of a previously uploaded file. + minLength: 1, maxLength: 128 + - `type: "file"` - - `"file"` - - `mount_path: optional string or null` Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`. - - `BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }` + minLength: 1, maxLength: 4096 + + - `BetaManagedAgentsMemoryStoreResourceParam object` Parameters for attaching a memory store to an agent session.
from line 1024
- `type: "memory_store"` - - `"memory_store"` - - `access: optional "read_write" or "read_only" or null` Access mode for an attached memory store.
from line 1036
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. + maxLength: 4096 + - `title: optional string or null` Human-readable session title. + maxLength: 500 + - `vault_ids: optional array of string` Vault IDs for stored credentials the agent can use during the session. -### Returns - -- `BetaManagedAgentsSession object { id, agent, archived_at, 14 more }` +## Returns + +- `BetaManagedAgentsSession object` A Managed Agents `session`.
from line 1070
- `type: "url"` - - `"url"` - - `url: string` - `model: BetaManagedAgentsModelConfig`
from line 1146
How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes. - - `BetaManagedAgentsEffortLow object { type }` + - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - - `"low"` - - - `BetaManagedAgentsEffortMedium object { type }` + - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - - `"medium"` - - - `BetaManagedAgentsEffortHigh object { type }` + - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - - `"high"` - - - `BetaManagedAgentsEffortXhigh object { type }` + - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - - `"xhigh"` - - - `BetaManagedAgentsEffortMax object { type }` + - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - - `"max"` - - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1196
Full `agent` definitions the coordinator may spawn as session threads. - - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }` + - `BetaManagedAgentsSessionThreadAgent object` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.
from line 1220
- `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }` + - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill.
from line 1228
- `type: "anthropic"` - - `"anthropic"` - - `version: string` - - `BetaManagedAgentsCustomSkill object { skill_id, type, version }` + - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill.
from line 1238
- `type: "custom"` - - `"custom"` - - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }` + - `BetaManagedAgentsAgentToolset20260401 object` - `configs: array of BetaManagedAgentsAgentToolConfig` - - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool.
from line 1256
- `name: "bash"` - - `"bash"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - - `"always_allow"` - - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - - `"always_ask"` - - `type: "bash"` - - `"bash"` - - - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool.
from line 1282
- `name: "edit"` - - `"edit"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "edit"` - - `"edit"` - - - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool.
from line 1304
- `name: "read"` - - `"read"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "read"` - - `"read"` - - - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool.
from line 1326
- `name: "write"` - - `"write"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "write"` - - `"write"` - - - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool.
from line 1348
- `name: "glob"` - - `"glob"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "glob"` - - `"glob"` - - - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool.
from line 1370
- `name: "grep"` - - `"grep"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "grep"` - - `"grep"` - - - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }` + - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool.
from line 1392
- `name: "web_fetch"` - - `"web_fetch"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "web_fetch"` - - `"web_fetch"` - - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` - - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }` + format: int32 + + - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool.
from line 1422
- `name: "web_search"` - - `"web_search"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "web_search"` - - `"web_search"` - - `allowed_domains: optional array of string` - `blocked_domains: optional array of string`
from line 1448
Location precision. Only "approximate" is supported. - - `"approximate"` - - `city: optional string or null` City name. + minLength: 1, maxLength: 255 + - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase.
from line 1462
Region or state name. + minLength: 1, maxLength: 255 + - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". + minLength: 1, maxLength: 255 + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools.
from line 1480
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - - `"agent_toolset_20260401"` - - - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }` + - `BetaManagedAgentsMCPToolset object` - `configs: array of BetaManagedAgentsMCPToolConfig`
from line 1502
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution.
from line 1520
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution.
from line 1532
- `type: "mcp_toolset"` - - `"mcp_toolset"` - - - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }` + - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses.
from line 1544
- `type: "object"` - - `"object"` - - `properties: optional map[unknown] or null` - `required: optional array of string or null`
from line 1552
- `type: "custom"` - - `"custom"` - - `type: "agent"` - - `"agent"` - - `version: number` - - `BetaManagedAgentsAdvisor object { model, type }` + format: int32 + + - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
from line 1568
- `type: "advisor"` - - `"advisor"` - - `type: "coordinator"` - - `"coordinator"` - - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }` + - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - - `BetaManagedAgentsCustomSkill object { skill_id, type, version }` + - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill.
from line 1586
- `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }` - - - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }` - - - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }` + - `BetaManagedAgentsAgentToolset20260401 object` + + - `BetaManagedAgentsMCPToolset object` + + - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "agent"` - - `"agent"` - - `version: number` + format: int32 + - `archived_at: string or null` A timestamp in RFC 3339 format + format: date-time + - `budget: BetaManagedAgentsBudgetLimit or null` A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 1622
Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - - `"USD"` - - `type: "limit"` - - `"limit"` - - `created_at: string` A timestamp in RFC 3339 format + format: date-time + - `environment_id: string` - `metadata: map[string]`
from line 1642
A timestamp in RFC 3339 format + format: date-time + - `description: string` What the agent should produce.
from line 1656
0-indexed revision cycle the outcome is currently on. + format: int32 + - `outcome_id: string` Server-generated outc_ ID for this outcome.
from line 1668
- `type: "outcome_evaluation"` - - `"outcome_evaluation"` - - `resources: array of BetaManagedAgentsSessionResource` - - `BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }` + - `BetaManagedAgentsGitHubRepositoryResource object` - `id: string`
from line 1678
A timestamp in RFC 3339 format + format: date-time + - `mount_path: string` - `type: "github_repository"` - - `"github_repository"` - - `updated_at: string` A timestamp in RFC 3339 format + format: date-time + - `url: string` - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null` - - `BetaManagedAgentsBranchCheckout object { name, type }` + - `BetaManagedAgentsBranchCheckout object` - `name: string` Branch name to check out. + minLength: 1, maxLength: 255 + - `type: "branch"` - - `"branch"` - - - `BetaManagedAgentsCommitCheckout object { sha, type }` + - `BetaManagedAgentsCommitCheckout object` - `sha: string` Full commit SHA to check out. + minLength: 7, maxLength: 64 + - `type: "commit"` - - `"commit"` - - - `BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }` + - `BetaManagedAgentsFileResource object` - `id: string`
from line 1722
A timestamp in RFC 3339 format + format: date-time + - `file_id: string` - `mount_path: string` - `type: "file"` - - `"file"` - - `updated_at: string` A timestamp in RFC 3339 format - - `BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }` + format: date-time + + - `BetaManagedAgentsMemoryStoreResource object` A memory store attached to an agent session.
from line 1746
- `type: "memory_store"` - - `"memory_store"` - - `access: optional "read_write" or "read_only" or null` Access mode for an attached memory store.
from line 1762
Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. + maxLength: 4096 + - `mount_path: optional string or null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only.
from line 1780
Cumulative time in seconds the session spent in running status. Excludes idle time. + format: double + - `duration_seconds: optional number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. + format: double + - `status: "rescheduling" or "running" or "idle" or "terminated"` SessionStatus enum
from line 1804
- `type: "session"` - - `"session"` - - `updated_at: string` A timestamp in RFC 3339 format + format: date-time + - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for a session across all turns.
from line 1818
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. + format: double + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime.
from line 1828
Tokens used to create 1-hour ephemeral cache entries. + format: int32 + - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. + format: int32 + - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. + format: int32 + - `input_tokens: optional number` Total input tokens consumed across all turns. + format: int32 + - `list_cost: optional BetaMonetaryAmount or null` A monetary amount in a specific currency.
from line 1856
Total output tokens generated across all turns. + format: int32 + - `server_tool_use: optional BetaManagedAgentsServerToolUsage or null` Cumulative count of server-executed tool invocations, broken down by tool.
from line 1866
Number of server-executed web fetch requests. + format: int32 + - `web_search_requests: optional number` Number of server-executed web search requests. + format: int32 + - `vault_ids: array of string` Vault IDs attached to the session at creation. Empty when no vaults were supplied.
from line 1882
Deployment ID when the session was created from a deployment reference. Null otherwise. -### Example - -```http +## Example + +```bash curl https://api.anthropic.com/v1/sessions \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \
from line 1897
}' ``` -#### Response +### Response (200) ```json {