Create Session

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

POST /agent/v1/sessions◐ Partial

Request body

modelstring可选
The model powering the agent: a model name string (e.g. claude-opus-5) or an object for extra configuration (see subfields).
agentstring | object必填
The agent the session runs: an agent ID string (pins the latest version) or an object with id and version (see subfields).
▸ 展开子字段（8）
- idstring必填
  The ID of the agent the session runs.
- typestring必填
  Reference type; only agent today.
  取值 agent_with_overrides
- versionnumber可选
  The specific agent version to pin; omit for the latest.
- mcp_serversarray可选
  Replacement MCP server list for this session: the provided array applies wholesale; an empty array clears, omitting keeps the agent's configuration.
- modelstring | object可选
  Replacement model for this session: a model name string (e.g. claude-opus-5) or a config object; omit to keep the agent's model.
- skillsarray可选
  Replacement skill list for this session; an empty array clears, omitting keeps the agent's skills.
- systemstring可选
  Replacement system prompt for this session, up to 100,000 characters; null clears it, omitting keeps the agent's.
- toolsarray可选
  Replacement tool configuration for this session; an empty array clears, omitting keeps the agent's.
environment_idstring可选
ID of the environment the session runs in; it determines the container's base environment.
titlestring可选
Human-readable session title.
metadataobject可选
Custom metadata key-value pairs for the session.
budgetobject可选
Spending cap for the session.
▸ 展开子字段（2）
- max_list_costobject必填
  Cap on list-call spending within the budget.
- typestring必填
  Budget type; only max_list_cost today.
  取值 limit
initial_eventsarray可选
Initial events sent to the session in order at creation; user.message and user.define_outcome are supported, up to 50.
resourcesarray可选
Resources (e.g. repositories, files) to mount into the session's container.
vault_idsarray可选
Vault IDs for stored credentials the agent can use during the session.
cwdstring可选
默认 "/home/user/workspace"
Session working directory on any machine. Must be an absolute path within /home/user with no . or .. segments. Repeated and trailing slashes are normalized. Invalid values return 400 invalid_request_error with Invalid cwd.
▸ 更多参数（3）
- computer_idstring可选
  Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined.
- time_zonestring可选
  默认 "UTC"
  Praxis extension: the session's IANA time zone name (e.g. Asia/Shanghai) — the clock the runtime environment block renders for every turn. Absent means UTC. Only IANA names are accepted; fixed offsets ("+08:00") and unknown names return 400. Never stored in `metadata`.
- thinkingobject可选
  Praxis extension: explicit session thinking effort; null inherits the pinned agent default, then the model default. none disables thinking only when model.thinking.can_disable is true. Unsupported efforts return 400 invalid_request_error.
  ▸ 展开子字段（1）
  - effortstring必填
    Thinking level for this session. The model must support the chosen effort; none requires can_disable. Null on thinking restores inheritance from the agent and model.
    取值 lowmediumhighxhighnone

Returns

200

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

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

Response

HTTP 201

Successful response

application/json

Name	Type	Description
id	string	Session id (sesn_...). Pass it as session_id in every session call.
agent	object	Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
agent.id	string	Agent id (agent_...). Pass it as agent when creating a session and as agent_id in agent calls.
agent.description	null \| string	Free-text description of what the agent is for; null when none was set.
agent.mcp_servers	array<object>	URL MCP servers the agent can call, paired one-to-one with mcp_toolset entries in tools and saved with the agent version. No credentials are stored here.
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	Display name of the agent, as set on create or update. It is a label, not a unique key.
agent.skills	array<object>	Skill attachments are not supported: a nonempty skills array returns 400. Omit this field or send an empty array. The native Skill tool loads available runtime skills independently of this field.
agent.system	null \| string	System prompt given to the model at the start of every session of this agent; null when none was set.
agent.tools	array<object>	Tools of the agent: one agent_toolset_20260401 entry for the native tools (all resolved settings are returned, ready to send back on update), plus mcp_toolset entries; custom tool definitions are rejected with 400. Keep bash enabled to use codemode, Skill and subagents.
agent.type	string	Always `agent`. An agent definition.
agent.version	number	The agent's current version. Starts at 1 and increments each time the agent is modified.
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	Always `limit`. A spending limit.
created_at	string	A timestamp in RFC 3339 format
environment_id	string	Id of the environment recipe the session's sandbox was created from. Omitted when no recipe was selected, that is, for a light machine or the Computer chosen by computer_id.
metadata	object	Free-form string key/value pairs stored with the session, changed through sessions.update patch semantics.
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	Always `outcome_evaluation`. Record of one outcome evaluation.
resources	array<object>	Resources attached to the session, at most 500; each is a file reference mounted into the session's machine.
resources[].id	string	Resource id, the resource_id of sessions.resources calls.
resources[].created_at	string	A timestamp in RFC 3339 format
resources[].mount_path	string \| null \| string	Path inside the machine where the file is mounted; defaults to /mnt/session/uploads/<file_id>, and custom paths are rooted there. / 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	Always `github_repository`. A GitHub repository resource; not supported on this platform. / Always `file`. A file resource: an uploaded file mounted into the session's machine. / Always `memory_store`. A memory store resource; not supported on this platform.
resources[].updated_at	string	A timestamp in RFC 3339 format
resources[].url	string	Repository URL.
resources[].checkout	null \| object	Branch or commit to check out.
resources[].file_id	string	Id of the uploaded file; it must exist and belong to your tenant.
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	Title of the session, set on create or through sessions.update; null when none was set.
type	string	Always `session`. A session, one conversation of an agent on a machine.
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.
cwd	string	Normalized session working directory; defaults to /home/user/workspace. Forks inherit this directory.
computer_id	string	Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. computer_id selects a tenant-owned active computer. Session selection overrides the agent default; a sandbox environment_id and computer_id cannot be combined. Omitted when no computer is selected.
model	object	Praxis extension: the currently selected session model.
model.id	string	Identifier of the object, as returned by the API; pass it in the path of follow-up calls on the same resource.
model.thinking	object \| null	Supported thinking controls, or null when capability is unknown or unavailable. efforts lists selectable strengths; can_disable permits none; default_effort is nullable.
thinking	object \| null	Praxis extension: explicit session thinking effort; null inherits the pinned agent default, then the model default. none disables thinking only when model.thinking.can_disable is true. Unsupported efforts return 400 invalid_request_error.
thinking.effort	string	Thinking level saved for this session: low, medium, high, xhigh, or none to turn thinking off. Null or absent means the session inherits the agent default and then the model default.
forked_from	object \| null	Praxis extension: source of a forked session; null for other sessions. Available only on /agent/v1.
forked_from.session_id	string	Id of the parent session this session was forked from; it is left unchanged by the fork.
forked_from.message_id	string	message_id of the agent message in the parent session up to which the conversation was copied.