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 managedAgentsGetSession or subscribe with managedAgentsStreamSessionEvents 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 exact HTTP method, escaped path, raw query, and raw body bytes returns the original session; any difference is rejected. A reasoning_effort incompatible with the selected model or its frozen output capacity returns 400 before provisioning. Enabled provider_params.promptCacheTTL or provider_params.promptCacheSharedTTL settings with invalid values, an unsupported model, or shared retention shorter than history retention also return 400 before provisioning for the selected root agent version, including for previously stored agent versions. Roster agent cache settings are validated at delegation before creating each child session. 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 managedAgentsCreateEnvironmentSetupRun first. When the tenant is out of credit it returns 403 session_start_not_admitted with details.reason out_of_credit; add credits and retry. When the tenant is suspended it returns the same 403 with details.reason tenant_suspended. A budget above the agent’s multiagent.limits.max_tree_cost_usd returns 400. When the tenant already has as many sessions working at once as it may, it returns 429 tenant_concurrency_limit with details.limit; wait for a session to finish its turn or stop one, then retry.
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. 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.
1 - 256^[!-~]+$Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.
1Organization 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.
1Body
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 /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.
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.
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 /managed-agents/v1/environments or GET /managed-agents/v1/environments.
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 /managed-agents/v1/sessions.
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.
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.
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.
- Option 1
- Option 2
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.
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.
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 when the agent version defines a default_rubric. Omit when the version has no rubric.
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 /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.
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.
Canonical programmatic-host path to the accepted session.
^/managed-agents/v1/sessions/[^/?]+$