Update Session

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

POST /agent/v1/sessions/{session_id}◐ Partial

Request parameters

session_idstring必填
path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.
modelstring可选
Extension: model ID from the session’s pinned version models.allowed, or its default model when no list exists. Applies on the next turn without interrupting the current turn. No context-window check is performed here.
agentobject可选
The agent the session runs: an agent ID string (pins the latest version) or an object with id and version (see subfields).
▸ 展开子字段（2）
- mcp_serversarray可选
  Replacement MCP server list for this session: the provided array applies wholesale; an empty array clears, omitting keeps the agent's configuration.
- toolsarray可选
  Replacement tool configuration for this session; an empty array clears, omitting keeps the agent's.
titlestring可选
Human-readable session title.
metadataobject可选
Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.
budgetobject可选
A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
▸ 展开子字段（2）
- max_list_costobject必填
  Cap on list-call spending within the budget.
- typestring必填
  Budget type; only max_list_cost today.
  取值 limit
vault_idsarray可选
Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.
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

Optional model is an ID in the pinned version allowed list; thinking is {effort: "low|medium|high|xhigh|none"} or null. Omission preserves the selection; null restores inheritance. A model-only change clears unsupported session thinking. Combined updates validate against the new model; invalid choices return 400 and preserve the previous selection. Changes affect the next turn, not an in-flight turn. Example: {"model":"deepseek-v4-flash","thinking":{"effort":"xhigh"}}. Responses include thinking and model.thinking: {efforts, can_disable, default_effort}; unknown capability is null. These fields are available only on /agent/v1. Supports title and metadata with the official patch semantics: a string value upserts the key, null deletes it, a whole-null object clears the bag, and untouched keys are preserved. The official agent override (tools/mcp_servers), budget and vault_ids are not supported and return 400 naming the field. Updating an archived session returns 409.

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

Response

HTTP 200

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.