Create a new session
POST /v1/sessions
Request Body required
Section titled “Request Body required ”Request to create a session
object
ID of the agent to work in this session (optional, format: agent_{32-hex}).
Example
agent_01933b5a00007000800000000000001Optional resident agent identity used for unattended/background execution.
Example
identity_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
ID of the harness for this session (format: harness_{32-hex}). If omitted, the org base harness is used. New orgs default that to Base.
Example
harness_01933b5a00007000800000000000001Session-level client hints — arbitrary key-value pairs that tell the
server what the client can handle. These are defaults for every turn;
per-message controls.hints override these key-by-key (shallow merge).
Examples: {"setup_connection": true, "rich_media": true}
Session-level initial files (additive to agent initial_files). Files with matching paths override agent/harness files; new paths are appended.
Starter file copied into a new session from an agent or harness.
object
File content: plain text or base64-encoded binary.
Content encoding: text or base64.
Prevent session-side edits or deletes when true.
Absolute path within the session workspace. /workspace prefix is accepted.
Session locale (BCP 47, e.g. uk-UA).
Example
uk-UAThe ID of the LLM model to use for this session. Overrides the agent’s default model if specified.
Example
model_01933b5a00007000800000000000001Optional session-level system prompt override. Prepended to the agent’s system prompt when building RuntimeAgent.
Tags for organizing and filtering sessions.
Example
[ "debugging", "urgent"]Human-readable title for the session.
Example
Debug login issueClient-side tools for this session (additive to agent tools). These tools are sent to the LLM but executed by the client.
Built-in tool - executed by the worker via ToolRegistry
object
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Semantic hints describing the tool’s behavioral properties
object
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
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
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering
Semantic hints describing the tool’s behavioral properties
object
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
Tool name (used by LLM and for correlation)
JSON schema for tool parameters
Responses
Section titled “ Responses ”Session created 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_01933b5a00007000800000000000001Optional resident agent identity for unattended/background execution.
Example
identity_01933b5a00007000800000000000001Validated config passed by host at blueprint spawn time.
Blueprint ID. When set, reason_activity and act_activity build RuntimeAgent from the blueprint definition instead of from harness_id/agent_id.
Session-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”, “leased_resources”.
Timestamp when the session finished (completed or failed).
ID of the harness for this session (format: harness_{32-hex}).
Example
harness_01933b5a00007000800000000000001Session-level client hints — arbitrary key-value pairs declared by the
client at session creation time. These are defaults for every turn;
per-message controls.hints override these key-by-key (shallow merge).
Examples: {"setup_connection": true, "rich_media": true}
Unique identifier for the session (format: session_{32-hex}).
Example
session_01933b5a00007000800000000000001Session-level initial files (additive to agent initial_files). Files with matching paths override agent/harness files; new paths are appended.
Starter file copied into a new session from an agent or harness.
object
File content: plain text or base64-encoded binary.
Content encoding: text or base64.
Prevent session-side edits or deletes when true.
Absolute path within the session workspace. /workspace prefix is accepted.
Whether this session is pinned by the current user. Only populated when the request has an authenticated user context.
Locale for localized agent behavior and formatting (BCP 47, e.g. uk-UA).
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).
Parent session that spawned this subagent. NULL for top-level sessions.
Preview text from the first user message (truncated).
Timestamp when the session started executing.
Current execution status of the session.
Human-readable subagent name (“Test Runner”), unique per parent.
Original task description given to this subagent.
Session-level system prompt override. Prepended to the agent’s system prompt when building RuntimeAgent.
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
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Semantic hints describing the tool’s behavioral properties
object
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
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
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering
Semantic hints describing the tool’s behavioral properties
object
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
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
Harness, Agent, or Model not found
Internal server error