Start a managed session
Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Requires an Idempotency-Key header: the same key with the same body returns the original session, and with a different body is rejected. A reasoning_effort incompatible with the selected model or its frozen output capacity returns 400 before provisioning; a temporarily unavailable model reference or catalog dependency returns 503. An environment on managed compute whose setup script has no verified, current run returns 422 environment_not_verified before provisioning; run createEnvironmentSetupRun first.
Authorizations
A Recursion API key, created in the console under API keys.
Headers
Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.
1 - 256^[!-~]+$Body
Request body for starting a session: which agent to run, the environment to run it in, the vault grants it receives, and the opening message and/or outcome that gives it work.
The agent to run, from POST /v1/agents or GET /v1/agents. Its current version is snapshotted into the session, so later edits to the agent do not affect this run.
Optional per-item allowlist inside vault_ids. The list is a whitelist across every granted vault, not a filter within one, so it must name every item the session should receive. Omit with explicit vault_ids to enable all items; [] alongside a non-empty vault_ids is rejected because it would enable none. Omit both fields to use the agent version's defaults.
The environment whose sandbox the session runs in, from POST /v1/environments or GET /v1/environments. Required for ordinary agents; evaluation agents omit it because the run has no parent sandbox and each child clones its target workspace.
Target session snapshots for an evaluation agent. Set exactly one of session_ids or statuses plus limit; targets are resolved server-side within the caller's organization and public-session scope before the run is created.
Stable identity inside the external system, e.g. a Slack thread key or a pull-request key. Set together with external_source_type.
Kind of external system this session correlates to, e.g. slack or github. Set together with external_source_id; sessions can then be filtered by both on GET /v1/sessions.
Opening user message for the session, and the context the agent works from. Send it alongside an outcome to supply facts the agent needs without making them part of what the grader measures; the grader never sees it. Kept in the session's system prompt for the whole run, so context compaction cannot summarize it away.
Caller-defined string key/value pairs stored on the session, e.g. ids that map it back to your own system. Write-once: they cannot be changed after start. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters without control characters. Returned as metadata on GET /v1/sessions and filterable with metadata=key:value (repeatable, AND) or metadata_key=key.
Optional definition of done, graded against a rubric. Its description is the objective and is quoted to the grader; send a message alongside it for context the grader should not see. With no message the description opens the session. Omit to inherit the agent version's default_rubric when it defines one, graded against this request's message; an outcome sent here is used as given and the agent default is ignored entirely.
Prior sessions this one may read, by session id. Each grants read access to the whole tree containing it -- transcript, agents, tools, cost, outcome, and output files -- through a set of read-only tools offered to the agent only when at least one reference exists. Each id is authorized under your own scope, so a session you cannot read refuses the whole request with 404 and starts nothing. Sessions from another organization, admin_only sessions, and session analysts are never referenceable. More may be added later with referenced_session_ids on POST /v1/sessions/{session_id}/events.
10Files to mount read-only into the session's sandbox, under its files directory, before the first turn. Each attaches the file's content as it is now. All-or-nothing: one unknown or out-of-scope file_id refuses the whole request with 404 and creates nothing. Requires an environment with a sandbox.
500Start ungraded even when the agent version defines a default_rubric. Only needed for an agent that has one, since omitting outcome otherwise inherits it.
How this session's tree may work as a team. Every tree has a shared task board: under mode auto (the default) the agent becomes a team the moment it posts its first task, recruiting copies of itself one per claimable task, which share its sandbox, claim work from the board, and are woken by its transitions; mode on makes it a team from turn one; mode off withholds the board. Overrides the agent's multiagent.team mode for this session; an agent with no roster runs under default limits. Governance (thread and cost caps) is the agent's and cannot be widened here.
Vault grants for this session. Omit to use the agent version's default_vault_ids; send [] to disable all defaults.
Response
Response body of POST /v1/sessions, returned with HTTP 202 and a Location header. The 202 is load-bearing: the session is accepted, not started, so no status, sandbox, or event exists yet and nothing here reports success of the run. Poll status_path, or stream events, to observe provisioning and execution.
Response body of POST /v1/sessions, returned with HTTP 202 and a Location header. The 202 is load-bearing: the session is accepted, not started, so no status, sandbox, or event exists yet and nothing here reports success of the run. Poll status_path, or stream events, to observe provisioning and execution.
Identifier for this session (UUID). Server-assigned. Derived deterministically from the Idempotency-Key when one was sent, so a retried create returns the same id rather than starting a second session.
Path to poll for provisioning, execution, and structured failure state.