Update session
PATCH /v1/sessions/{session_id}
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Session ID (prefixed, e.g., session_…)
Request Body required
Section titled “Request Body required ”Request to update a session. Only provided fields will be updated.
object
Tags for organizing and filtering sessions.
Example
[ "resolved"]Human-readable title for the session.
Example
Updated session titleResponses
Section titled “ Responses ”Session updated successfully
Session - instance of agentic loop execution. A session represents a single conversation with an agent.
object
Number of active (enabled) schedules for this session. Populated when the session is fetched for API responses.
ID of the agent working in this session (format: agent_{32-hex}). Optional.
Example
agent_01933b5a00007000800000000000001Session-level capabilities (additive to agent capabilities). Applied after agent capabilities when building RuntimeAgent.
Per-agent capability configuration
Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.
object
Per-agent configuration for this capability (capability-specific)
Reference to the capability ID
Timestamp when the session was created.
Aggregated UI features from all active capabilities (harness + agent + session). Computed at read time from the capability registry. Known features: “file_system”, “schedules”, “secrets”, “key_value”, “sql_database”.
Timestamp when the session finished (completed or failed).
ID of the harness for this session (format: harness_{32-hex}).
Example
harness_01933b5a00007000800000000000001Unique identifier for the session (format: session_{32-hex}).
Example
session_01933b5a00007000800000000000001Whether this session is pinned by the current user. Only populated when the request has an authenticated user context.
LLM model ID to use for this session (format: model_{32-hex}). Overrides the agent’s default model if set.
Example
model_01933b5a00007000800000000000001Organization this session belongs to (format: org_{32-hex}).
Example
org_00000000000000000000000000000001Preview text from the last assistant response (truncated).
Preview text from the first user message (truncated).
Timestamp when the session started executing.
Current execution status of the session.
Tags for organizing and filtering sessions.
Human-readable title for the session.
Client-side tools for this session (additive to agent tools).
Built-in tool - executed by the worker via ToolRegistry
object
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Tool name (used by LLM and for registry lookup)
JSON schema for tool parameters
Tool policy (auto or requires_approval)
Client-side tool - executed by the client, not the server
object
Tool description for LLM
Human-readable display name for UI rendering
Tool name (used by LLM and for correlation)
JSON schema for tool parameters
Timestamp when the session was last updated.
Cumulative token usage for all LLM calls in this session.
object
Number of tokens written to cache (Anthropic-specific)
Number of tokens read from cache (reduces cost)
Number of input/prompt tokens
Number of output/completion tokens
Invalid session ID
Session not found
Internal server error