Skip to main content
POST
Start a managed session

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

Idempotency-Key
string
required

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. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. 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.

Required string length: 1 - 256
Pattern: ^[!-~]+$
x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Body

application/json

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.

agent_id
string
required

The agent to run, from POST /managed-agents/v1/agents or GET /managed-agents/v1/agents. Its current version is snapshotted into the session, so later edits to the agent do not affect this run.

budget
object

The most this session tree (the session and its threads) may spend, in US dollars at the billed price. Omit it to take the agent's multiagent.limits.max_tree_cost_usd, if it declares one, or run without a budget. A budget may tighten the agent's cap, never widen it. Reaching it pauses the session with stop_reason budget_reached; raise the session's budget to continue. Budgets are rolling out: where they are not available to the caller, a budget returns 400 and an omitted one starts the session without a budget.

credential_refs
object[]

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.

environment_id
string

The environment whose sandbox the session runs in, from POST /managed-agents/v1/environments or GET /managed-agents/v1/environments.

external_source_id
string

Stable identity inside the external system, e.g. a Slack thread key or a pull-request key. Set together with external_source_type.

external_source_type
string

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 /managed-agents/v1/sessions.

message
string

Opening user message for the session, and the context the agent works from. When sent alongside an explicit outcome, it supplies facts the agent needs without making them part of what the evaluator measures. When a graded default is inherited, this message becomes the objective quoted to the evaluator. Kept in the session's system prompt for the whole run, so context compaction cannot summarize it away. Omit it or send an empty string for none; a message of only whitespace is refused with 400.

metadata
object

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 /managed-agents/v1/sessions and filterable with metadata=key:value (repeatable, AND) or metadata_key=key.

outcome
object

Optional definition of done, graded against its rubric inside the session. Its description is the objective; send a message alongside it for context the grader should not measure. With no message the description opens the session. Omit to inherit the agent version's default_rubric, graded against this request's message; an outcome sent here is used as given and the agent default is ignored entirely.

Example:
project_id
string

Billing project this session is attributed to. Required when the agent runs on a model family that serves only named projects; refused with 400 for an organization whose model list has no such family.

referenced_session_ids
string[]

Prior readable sessions whose trees this session may use as context. Each id must be in the same organization and readable by the caller; otherwise the entire request returns 404. Session-analyst conversations cannot be referenced.

Maximum array length: 10
resources
object[]

Files 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.

Maximum array length: 500
skip_default_outcome
boolean

Start ungraded when the agent version defines a default_rubric. Omit when the version has no rubric.

team
object

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_ids
string[]

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 /managed-agents/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 /managed-agents/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.

session_id
string
required

Identifier for this session (UUID). Server-assigned. Derived deterministically from the durable idempotency receipt for a keyed request, so an exact retry returns the same id rather than starting a second session.

status_path
string
required

Canonical programmatic-host path to the accepted session.

Pattern: ^/managed-agents/v1/sessions/[^/?]+$