Create Session

Call Create agent first and replace the example agent ID with its returned ID.

POST /anthropic/v1/sessions◐ Partial

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

Response

HTTP 200

Successful response

application/json

Name	Type	Description
id	string
agent	object	Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
agent.id	string
agent.description	null \| string
agent.mcp_servers	array<object>
agent.model	object	Model identifier and configuration.
agent.multiagent	null \| object	Resolved coordinator topology with full agent definitions for each roster member.
agent.name	string
agent.skills	array<object>
agent.system	null \| string
agent.tools	array<object>
agent.type	string
agent.version	number
archived_at	null \| string	A timestamp in RFC 3339 format
budget	null \| object	A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
budget.max_list_cost	object	A monetary amount in a specific currency.
budget.type	string
created_at	string	A timestamp in RFC 3339 format
environment_id	string
metadata	object
outcome_evaluations	array<object>	Per-outcome evaluation state. One entry per `define_outcome` event sent to the session.
outcome_evaluations[].completed_at	null \| string	A timestamp in RFC 3339 format
outcome_evaluations[].description	string	What the agent should produce.
outcome_evaluations[].explanation	null \| string	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.
outcome_evaluations[].iteration	number	0-indexed revision cycle the outcome is currently on.
outcome_evaluations[].outcome_id	string	Server-generated outc_ ID for this outcome.
outcome_evaluations[].result	string	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.
outcome_evaluations[].type	string
resources	array<object>
resources[].id	string
resources[].created_at	string	A timestamp in RFC 3339 format
resources[].mount_path	string \| null \| string	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.
resources[].type	string
resources[].updated_at	string	A timestamp in RFC 3339 format
resources[].url	string
resources[].checkout	null \| object
resources[].file_id	string
resources[].memory_store_id	string	The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
resources[].access	null \| string	Access mode for an attached memory store.
resources[].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.
resources[].instructions	null \| string	Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
resources[].name	null \| string	Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.
stats	object	Timing statistics for a session.
stats.active_seconds	number	Cumulative time in seconds the session spent in `running` status. Excludes idle time.
stats.duration_seconds	number	Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.
status	string	SessionStatus enum - `rescheduling` - Transient error occurred, retrying automatically. - `running` - Agent is actively executing. - `idle` - Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `terminated` - Session has ended, either due to an error or completion.
title	null \| string
type	string
updated_at	string	A timestamp in RFC 3339 format
usage	object	Cumulative token usage for a session across all turns.
usage.active_seconds	number	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.
usage.cache_creation	object	Prompt-cache creation token usage broken down by cache lifetime.
usage.cache_read_input_tokens	number	Total tokens read from prompt cache.
usage.input_tokens	number	Total input tokens consumed across all turns.
usage.list_cost	null \| object	A monetary amount in a specific currency.
usage.output_tokens	number	Total output tokens generated across all turns.
usage.server_tool_use	null \| object	Cumulative count of server-executed tool invocations, broken down by tool.
vault_ids	array<string>	Vault IDs attached to the session at creation. Empty when no vaults were supplied.
deployment_id	null \| string	Deployment ID when the session was created from a deployment reference. Null otherwise.