---
title: "Create Session"
method: POST
path: "/v1/sessions?beta=true"
---

# Create Session

`POST /v1/sessions?beta=true`

## Headers

- `anthropic-version` string
- `anthropic-beta` string

## Request body

- BetaManagedAgentsCreateSessionParams — Request parameters for creating a `session`.
  - `agent` union, required
    - string
    - BetaManagedAgentsAgentParams — Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
      - `type` 'agent', required
      - `id` string, required — The `agent` ID.
      - `version` integer — The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
    - BetaManagedAgentsAgentWithOverridesParams — 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.
      - `type` 'agent_with_overrides', required
      - `id` string, required — The `agent` ID.
      - `version` integer — The specific `agent` version to use. Omit to use the latest version.
      - `model` union
        - union
          - string
          - 'claude-sonnet-5' — High-performance model for coding and agents
          - 'claude-fable-5' — Next generation of intelligence for the hardest knowledge work and coding problems
          - 'claude-opus-5' — Powerful intelligence for long-running agents and coding
          - 'claude-opus-4-8' — Powerful intelligence for long-running agents and coding
          - 'claude-opus-4-7' — Powerful intelligence for long-running agents and coding
          - 'claude-opus-4-6' — Powerful intelligence for long-running agents and coding
          - 'claude-sonnet-4-6' — Best combination of speed and intelligence
          - 'claude-haiku-4-5' — Fastest model with near-frontier intelligence
          - 'claude-haiku-4-5-20251001' — Fastest model with near-frontier intelligence
          - 'claude-opus-4-5' — Powerful intelligence for long-running agents and coding
          - 'claude-opus-4-5-20251101' — Powerful intelligence for long-running agents and coding
          - 'claude-sonnet-4-5' — High-performance model for agents and coding
          - 'claude-sonnet-4-5-20250929' — High-performance model for agents and coding
        - BetaManagedAgentsModelConfigParams — An object that defines additional configuration control over model use
          - `id` union, required — The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
            - string
            - 'claude-sonnet-5' — High-performance model for coding and agents
            - 'claude-fable-5' — Next generation of intelligence for the hardest knowledge work and coding problems
            - 'claude-opus-5' — Powerful intelligence for long-running agents and coding
            - 'claude-opus-4-8' — Powerful intelligence for long-running agents and coding
            - 'claude-opus-4-7' — Powerful intelligence for long-running agents and coding
            - 'claude-opus-4-6' — Powerful intelligence for long-running agents and coding
            - 'claude-sonnet-4-6' — Best combination of speed and intelligence
            - 'claude-haiku-4-5' — Fastest model with near-frontier intelligence
            - 'claude-haiku-4-5-20251001' — Fastest model with near-frontier intelligence
            - 'claude-opus-4-5' — Powerful intelligence for long-running agents and coding
            - 'claude-opus-4-5-20251101' — Powerful intelligence for long-running agents and coding
            - 'claude-sonnet-4-5' — High-performance model for agents and coding
            - 'claude-sonnet-4-5-20250929' — High-performance model for agents and coding
          - `speed` 'standard' | 'fast' — Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
          - `effort` union
            - 'low' | 'medium' | 'high' | 'xhigh' | 'max' — How hard Claude works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time.
            - union — How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
              - …
          - `inference_geo` string, nullable — 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.
      - `system` string, nullable — Replacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it.
      - `tools` BetaManagedAgentsAgentToolParams[] — 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.
        - union — Union type for tool configurations in the tools array.
          - object — Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
            - `type` 'agent_toolset_20260401', required
            - `default_config` BetaManagedAgentsAgentToolsetDefaultConfigParams — Default configuration for all tools in a toolset.
              - …
            - `configs` BetaManagedAgentsAgentToolConfigParams[] — Per-tool configuration overrides.
              - …
          - object — Configuration for tools from an MCP server defined in `mcp_servers`.
            - `type` 'mcp_toolset', required
            - `mcp_server_name` string, required — Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
            - `default_config` BetaManagedAgentsMCPToolsetDefaultConfigParams — Default configuration for all tools from an MCP server.
              - …
            - `configs` BetaManagedAgentsMCPToolConfigParams[] — Per-tool configuration overrides.
              - …
          - 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.
            - `type` 'custom', required
            - `name` string, required — Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
            - `description` string, required — Description of what the tool does, shown to the agent to help it decide when to use the tool.
            - `input_schema` BetaManagedAgentsCustomToolInputSchema, required — JSON Schema for custom tool input parameters.
              - …
      - `mcp_servers` BetaManagedAgentsMCPServerParams[] — 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.
        - `type` 'url', required
        - `name` string, required — Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
        - `url` string, required — Endpoint URL for the MCP server.
      - `skills` BetaManagedAgentsSkillParams[] — Replacement skill list. Full replacement: the provided array becomes the skills. Send an empty array to clear; omit to preserve the agent's skills.
        - union — Skill to load in the session container.
          - BetaManagedAgentsAnthropicSkillParams — An Anthropic-managed skill.
            - `type` 'anthropic', required
            - `skill_id` string, required — Identifier of the Anthropic skill (e.g., "xlsx").
            - `version` string, nullable — Version to pin. Defaults to latest if omitted.
          - BetaManagedAgentsCustomSkillParams — A user-created custom skill.
            - `type` 'custom', required
            - `skill_id` string, required — Tagged ID of the custom skill (e.g., "skill_01XJ5...").
            - `version` string, nullable — Version to pin. Defaults to latest if omitted.
  - `environment_id` string, required — ID of the `environment` defining the container configuration for this session.
  - `title` string, nullable — Human-readable session title.
  - `metadata` object — Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
  - `resources` BetaManagedAgentsSessionResourceParams[] — Resources (e.g. repositories, files) to mount into the session's container.
    - union — Union of resources that can be mounted into a session.
      - object — Mount a GitHub repository into the session's container.
        - `type` 'github_repository', required
        - `url` string, required — Github URL of the repository
        - `authorization_token` string, required — GitHub authorization token used to clone the repository.
        - `mount_path` string, nullable — Mount path in the container. Defaults to `/workspace/<repo-name>`.
        - `checkout` union
          - object
            - `type` 'branch', required
            - `name` string, required — Branch name to check out.
          - object
            - `type` 'commit', required
            - `sha` string, required — Full commit SHA to check out.
      - object — Mount a file uploaded via the Files API into the session.
        - `type` 'file', required
        - `file_id` string, required — ID of a previously uploaded file.
        - `mount_path` string, nullable — Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
      - object — Parameters for attaching a memory store to an agent session.
        - `type` 'memory_store', required
        - `memory_store_id` string, required — The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
        - `access` 'read_write' | 'read_only' — Access mode for an attached memory store.
        - `instructions` string, nullable — Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
  - `vault_ids` string[] — Vault IDs for stored credentials the agent can use during the session.
  - `initial_events` BetaManagedAgentsSessionInitialEventParams[] — Initial events to send to the `session` at creation, processed in order. Supports `user.message` and `user.define_outcome` events. Maximum 50 events.
    - union — An event sent to the `session` immediately after it is created. Supports `user.message` and `user.define_outcome`.
      - object — Parameters for sending a user message to the session.
        - `type` 'user.message', required
        - `content` BetaManagedAgentsUserContentBlock[], required — Array of content blocks for the user message.
          - union — Content block in a user message. Can be `text`, `image`, or `document`.
            - object — Regular text content.
              - …
            - object — Image content specified directly as base64 data or as a reference via a URL.
              - …
            - object — Document content, either specified directly as base64 data, as text, or as a reference via a URL.
              - …
            - object — Placeholder for content withheld by Anthropic model policy.
              - …
      - object — Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
        - `type` 'user.define_outcome', required
        - `description` string, required — What the agent should produce. This is the task specification.
        - `rubric` union, required — Rubric for grading the quality of an outcome.
          - BetaManagedAgentsFileRubricParams — Rubric referenced by a file uploaded via the Files API.
            - `type` 'file', required
            - `file_id` string, required — ID of the rubric file.
          - BetaManagedAgentsTextRubricParams — Rubric content provided inline as text.
            - `type` 'text', required
            - `content` string, required — Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
        - `max_iterations` integer, nullable — Eval→revision cycles before giving up. Default 3, max 20.
  - `budget` BetaManagedAgentsBudget — A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
    - `type` 'limit', required
    - `max_list_cost` BetaMonetaryAmount, required — A monetary amount in a specific currency.
      - `currency` 'USD', required
      - `amount` string, required — Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

## Response `200`

Successful response (OK)

- BetaManagedAgentsSession — A Managed Agents `session`.
  - `type` 'session', required
  - `id` string, required
  - `status` 'rescheduling' | 'running' | 'idle' | 'terminated', required — SessionStatus enum
  - `created_at` string, date-time, required — A timestamp in RFC 3339 format
  - `updated_at` string, date-time, required — A timestamp in RFC 3339 format
  - `environment_id` string, required
  - `title` string, nullable, required
  - `metadata` object, required
  - `agent` BetaManagedAgentsSessionAgent, required — Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
    - `type` 'agent', required
    - `id` string, required
    - `version` integer, required
    - `name` string, required
    - `description` string, nullable, required
    - `model` BetaManagedAgentsModelConfig, required — Model identifier and configuration.
      - `id` union, required — The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
        - string
        - 'claude-sonnet-5' — High-performance model for coding and agents
        - 'claude-fable-5' — Next generation of intelligence for the hardest knowledge work and coding problems
        - 'claude-opus-5' — Powerful intelligence for long-running agents and coding
        - 'claude-opus-4-8' — Powerful intelligence for long-running agents and coding
        - 'claude-opus-4-7' — Powerful intelligence for long-running agents and coding
        - 'claude-opus-4-6' — Powerful intelligence for long-running agents and coding
        - 'claude-sonnet-4-6' — Best combination of speed and intelligence
        - 'claude-haiku-4-5' — Fastest model with near-frontier intelligence
        - 'claude-haiku-4-5-20251001' — Fastest model with near-frontier intelligence
        - 'claude-opus-4-5' — Powerful intelligence for long-running agents and coding
        - 'claude-opus-4-5-20251101' — Powerful intelligence for long-running agents and coding
        - 'claude-sonnet-4-5' — High-performance model for agents and coding
        - 'claude-sonnet-4-5-20250929' — High-performance model for agents and coding
      - `speed` 'standard' | 'fast' — Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
      - `effort` union — How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
        - object — Low effort. Favors latency over reasoning depth.
          - `type` 'low', required
        - object — Medium effort. Balances latency and reasoning depth.
          - `type` 'medium', required
        - object — High effort. Favors reasoning depth.
          - `type` 'high', required
        - object — Extra-high effort. Not all models accept this level.
          - `type` 'xhigh', required
        - object — Maximum effort. Favors reasoning depth over latency.
          - `type` 'max', required
      - `inference_geo` string — Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
    - `system` string, nullable, required
    - `tools` BetaManagedAgentsAgentTool[], required
      - union — Union type for tool configurations returned in API responses.
        - object
          - `type` 'agent_toolset_20260401', required
          - `default_config` BetaManagedAgentsAgentToolsetDefaultConfig, required — Resolved default configuration for agent tools.
            - `enabled` boolean, required
            - `permission_policy` union, required — Permission policy for tool execution.
              - …
          - `configs` BetaManagedAgentsAgentToolConfig[], required
            - `name` 'bash' | 'edit' | 'read' | 'write' | 'glob' | 'grep' | 'web_fetch' | 'web_search', required — Built-in agent tool identifier.
            - `enabled` boolean, required
            - `permission_policy` union, required — Permission policy for tool execution.
              - …
        - object
          - `type` 'mcp_toolset', required
          - `mcp_server_name` string, required
          - `default_config` BetaManagedAgentsMCPToolsetDefaultConfig, required — Resolved default configuration for all tools from an MCP server.
            - `enabled` boolean, required
            - `permission_policy` union, required — Permission policy for tool execution.
              - …
          - `configs` BetaManagedAgentsMCPToolConfig[], required
            - `name` string, required
            - `enabled` boolean, required
            - `permission_policy` union, required — Permission policy for tool execution.
              - …
        - object — A custom tool as returned in API responses.
          - `type` 'custom', required
          - `name` string, required
          - `description` string, required
          - `input_schema` BetaManagedAgentsCustomToolInputSchema, required — JSON Schema for custom tool input parameters.
            - `properties` object, nullable
            - `required` string[], nullable
            - `type` 'object', required
    - `mcp_servers` BetaManagedAgentsMCPServer[], required
      - `type` 'url', required
      - `name` string, required
      - `url` string, required
    - `skills` BetaManagedAgentsSkill[], required
      - union — Resolved skill as returned in API responses.
        - BetaManagedAgentsAnthropicSkill — A resolved Anthropic-managed skill.
          - `type` 'anthropic', required
          - `skill_id` string, required
          - `version` string, required
        - BetaManagedAgentsCustomSkill — A resolved user-created custom skill.
          - `type` 'custom', required
          - `skill_id` string, required
          - `version` string, required
    - `multiagent` BetaManagedAgentsSessionMultiagent, required — Resolved coordinator topology with full agent definitions for each roster member.
      - `type` 'coordinator', required
      - `agents` BetaManagedAgentsSessionRosterEntry[], required — Full `agent` definitions the coordinator may spawn as session threads.
        - union — A session-resolved multiagent roster entry.
          - BetaManagedAgentsSessionThreadAgent — 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`.
            - `type` 'agent', required
            - `id` string, required
            - `version` integer, required
            - `name` string, required
            - `description` string, nullable, required
            - `model` BetaManagedAgentsModelConfig, required — Model identifier and configuration.
              - …
            - `system` string, nullable, required
            - `tools` BetaManagedAgentsAgentTool[], required
              - …
            - `mcp_servers` BetaManagedAgentsMCPServer[], required
              - …
            - `skills` BetaManagedAgentsSkill[], required
              - …
          - BetaManagedAgentsAdvisor — Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
            - `type` 'advisor', required
            - `model` string, required — The advisor model id.
  - `resources` BetaManagedAgentsSessionResource[], required
    - union
      - object
        - `type` 'github_repository', required
        - `id` string, required
        - `url` string, required
        - `mount_path` string, required
        - `checkout` union
          - object
            - `type` 'branch', required
            - `name` string, required — Branch name to check out.
          - object
            - `type` 'commit', required
            - `sha` string, required — Full commit SHA to check out.
        - `created_at` string, date-time, required — A timestamp in RFC 3339 format
        - `updated_at` string, date-time, required — A timestamp in RFC 3339 format
      - object
        - `type` 'file', required
        - `id` string, required
        - `file_id` string, required
        - `mount_path` string, required
        - `created_at` string, date-time, required — A timestamp in RFC 3339 format
        - `updated_at` string, date-time, required — A timestamp in RFC 3339 format
      - object — A memory store attached to an agent session.
        - `type` 'memory_store', required
        - `memory_store_id` string, required — The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
        - `access` 'read_write' | 'read_only' — Access mode for an attached memory store.
        - `name` string, nullable — Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
        - `description` string — Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description.
        - `instructions` string, nullable — Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
        - `mount_path` string, nullable — 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.
  - `vault_ids` string[], required — Vault IDs attached to the session at creation. Empty when no vaults were supplied.
  - `outcome_evaluations` BetaManagedAgentsOutcomeEvaluationResource[], required — Per-outcome evaluation state. One entry per define_outcome event sent to the session.
    - `type` 'outcome_evaluation', required
    - `outcome_id` string, required — Server-generated outc_ ID for this outcome.
    - `description` string, required — What the agent should produce.
    - `result` string, required — Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.
    - `iteration` integer, required — 0-indexed revision cycle the outcome is currently on.
    - `completed_at` string, date-time, required — A timestamp in RFC 3339 format
    - `explanation` string, nullable, required — Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable.
  - `usage` BetaManagedAgentsSessionUsage, required — Cumulative token usage for a session across all turns.
    - `input_tokens` integer — Total input tokens consumed across all turns.
    - `output_tokens` integer — Total output tokens generated across all turns.
    - `cache_read_input_tokens` integer — Total tokens read from prompt cache.
    - `cache_creation` BetaManagedAgentsCacheCreationUsage — Prompt-cache creation token usage broken down by cache lifetime.
      - `ephemeral_1h_input_tokens` integer — Tokens used to create 1-hour ephemeral cache entries.
      - `ephemeral_5m_input_tokens` integer — Tokens used to create 5-minute ephemeral cache entries.
    - `list_cost` BetaMonetaryAmount — A monetary amount in a specific currency.
      - `currency` 'USD', required
      - `amount` string, required — Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
    - `server_tool_use` BetaManagedAgentsServerToolUsage — Cumulative count of server-executed tool invocations, broken down by tool.
      - `web_search_requests` integer — Number of server-executed web search requests.
      - `web_fetch_requests` integer — Number of server-executed web fetch requests.
    - `active_seconds` number, double — 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.
  - `stats` BetaManagedAgentsSessionStats, required — Timing statistics for a session.
    - `duration_seconds` number, double — Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
    - `active_seconds` number, double — Cumulative time in seconds the session spent in running status. Excludes idle time.
  - `archived_at` string, date-time, required — A timestamp in RFC 3339 format
  - `deployment_id` string, nullable — Deployment ID when the session was created from a deployment reference. Null otherwise.
  - `budget` BetaManagedAgentsBudget, required — A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
    - `type` 'limit', required
    - `max_list_cost` BetaMonetaryAmount, required — A monetary amount in a specific currency.
      - `currency` 'USD', required
      - `amount` string, required — Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

## Other responses

- `400` — Invalid argument - The client specified an invalid argument
- `401` — Unauthenticated - The request does not have valid authentication credentials
- `403` — Permission denied - The caller does not have permission to execute the specified operation
- `404` — Not found - Some requested entity was not found
- `408` — Deadline exceeded - The deadline expired before the operation could complete
- `409` — Aborted - The operation was aborted due to concurrency issue
- `412` — Failed precondition - Operation was rejected because the system is not in required state
- `413` — Out of range - Operation was attempted past the valid range
- `429` — Resource exhausted - Some resource has been exhausted (rate limiting)
- `431` — Request header fields too large - Request metadata was too large
- `499` — Cancelled - The operation was cancelled by the client
- `500` — Internal - Internal server error
- `501` — Unimplemented - The operation is not implemented or supported
- `503` — Unavailable - The service is currently unavailable
- `504` — Deadline exceeded - Upstream service did not respond in time

---

[API](https://skmtc.net/anthropics/apis/anthropic-api.md) · [All operations](https://skmtc.net/anthropics/apis/anthropic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/anthropics/anthropic-api/versions/93d8fd7d6493/schema)