curl --request POST \
--url https://api.reasonmachines.com/v3/organizations/{orgId}/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Fix the flaky test in src/auth/session.test.ts and add a regression case.",
"repo": "acme/web",
"provider": "github",
"tags": [
"ci",
"tests"
]
}
'import requests
url = "https://api.reasonmachines.com/v3/organizations/{orgId}/sessions"
payload = {
"prompt": "Fix the flaky test in src/auth/session.test.ts and add a regression case.",
"repo": "acme/web",
"provider": "github",
"tags": ["ci", "tests"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: 'Fix the flaky test in src/auth/session.test.ts and add a regression case.',
repo: 'acme/web',
provider: 'github',
tags: ['ci', 'tests']
})
};
fetch('https://api.reasonmachines.com/v3/organizations/{orgId}/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.reasonmachines.com/v3/organizations/{orgId}/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'Fix the flaky test in src/auth/session.test.ts and add a regression case.',
'repo' => 'acme/web',
'provider' => 'github',
'tags' => [
'ci',
'tests'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.reasonmachines.com/v3/organizations/{orgId}/sessions"
payload := strings.NewReader("{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.reasonmachines.com/v3/organizations/{orgId}/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reasonmachines.com/v3/organizations/{orgId}/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"session_id": "<string>",
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"status": "running",
"session_policy": {
"version": 1,
"mode": "standard",
"components": {
"memoryRead": true,
"memoryWrite": true,
"skills": true,
"inheritedInstructions": true,
"integrations": true,
"secretInjection": true
},
"workspaceOwnership": "managed",
"personalContext": false,
"pullRequestPolicy": "draft_only"
},
"reason_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"runtime_profile": "runtime/reason-sync-yield-v1",
"experimental_runtime_profile": "runtime/reason-c2-tools-v7",
"experimental_runtime_features": [
"banner"
],
"model": "<string>",
"reasoning_effort": "<string>",
"allow_model_rollover": true,
"model_rolled_over": true,
"warnings": [
{
"code": "integration_needs_auth",
"message": "<string>",
"integration": "<string>",
"secret_name": "<string>"
}
]
}Create a session
Opens a new session from a prompt. Optional project_id files the session under an accessible existing Project (use GET /projects to discover IDs). A Project only groups sessions: it supplies no repository, machine, network hosts or execution target, so repo and target are the only selections. repo is optional: provide one to bind the initial checkout, or omit it for a repository-neutral start. If the running Brain later discovers an exact connected repository, Reason attaches it and continues the original task under this Session ID instead of creating another user task. The session starts immediately and runs asynchronously: poll GET /sessions/{id} for status and GET /sessions/{id}/events for incremental live output.
runcurl --request POST \
--url https://api.reasonmachines.com/v3/organizations/{orgId}/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Fix the flaky test in src/auth/session.test.ts and add a regression case.",
"repo": "acme/web",
"provider": "github",
"tags": [
"ci",
"tests"
]
}
'import requests
url = "https://api.reasonmachines.com/v3/organizations/{orgId}/sessions"
payload = {
"prompt": "Fix the flaky test in src/auth/session.test.ts and add a regression case.",
"repo": "acme/web",
"provider": "github",
"tags": ["ci", "tests"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: 'Fix the flaky test in src/auth/session.test.ts and add a regression case.',
repo: 'acme/web',
provider: 'github',
tags: ['ci', 'tests']
})
};
fetch('https://api.reasonmachines.com/v3/organizations/{orgId}/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.reasonmachines.com/v3/organizations/{orgId}/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'Fix the flaky test in src/auth/session.test.ts and add a regression case.',
'repo' => 'acme/web',
'provider' => 'github',
'tags' => [
'ci',
'tests'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.reasonmachines.com/v3/organizations/{orgId}/sessions"
payload := strings.NewReader("{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.reasonmachines.com/v3/organizations/{orgId}/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reasonmachines.com/v3/organizations/{orgId}/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"session_id": "<string>",
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"status": "running",
"session_policy": {
"version": 1,
"mode": "standard",
"components": {
"memoryRead": true,
"memoryWrite": true,
"skills": true,
"inheritedInstructions": true,
"integrations": true,
"secretInjection": true
},
"workspaceOwnership": "managed",
"personalContext": false,
"pullRequestPolicy": "draft_only"
},
"reason_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"runtime_profile": "runtime/reason-sync-yield-v1",
"experimental_runtime_profile": "runtime/reason-c2-tools-v7",
"experimental_runtime_features": [
"banner"
],
"model": "<string>",
"reasoning_effort": "<string>",
"allow_model_rollover": true,
"model_rolled_over": true,
"warnings": [
{
"code": "integration_needs_auth",
"message": "<string>",
"integration": "<string>",
"secret_name": "<string>"
}
]
}Authorizations
Your Reason API key from Settings › API keys. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, knowledge:read, memory:read, memory:write, skills:read, skills:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. network:read and network:write are opt-in, excluded from default keys. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).
Headers
Optional self-reported caller agent name. If absent, the server uses the User-Agent for external callers.
80Path Parameters
Organization id or slug. Resolve it with GET /v3/self.
Body
What the agent should do. Maximum 256 KiB when UTF-8 encoded.
How the Session runs. standard is for normal work, including API sessions targeting a local Mac: it keeps the configured capabilities and accepts follow-up messages. ephemeral runs one benchmark trial with the standard capabilities inside a single-use workspace from createEphemeralWorkspace: it needs that workspace, an externally-managed headless project_root and an idempotency_key, accepts no follow-up messages, and the workspace admits no other Session. The retired isolated mode returns 400 session_mode_retired, and the retired benchmark_profile and runtime_profile fields return 400 benchmark_profile_retired and runtime_profile_retired.
standard, ephemeral Who owns the persistence of the Session's filesystem, independently of mode: managed leaves it to Reason, externally-managed to the caller, which then has to target an explicit headless project_root. ara-managed is a deprecated spelling of managed, and responses report managed.
managed, externally-managed, ara-managed Whether the Session loads its creator's personal context: their personal skills, personal memory (profile and notes), personal secrets and personal connections. false runs it impersonally, on the workspace's and its Reason's own skills, memory, secrets and connections, the same for whoever created it; useful for automation that creates Sessions with someone's API key. The creator still owns the Session for permissions, billing and audit. Follow-ups, continuations and subagents keep the setting.
Restricts how the Session delivers pull requests. draft_only makes every pull request it opens a draft and refuses, in the server, marking one ready for review, merging, queueing or enabling auto-merge, adding labels, and publishing to the base or default branch; pr_merge is not granted, and the agent is told so. Omit for the normal delivery flow, in which the agent may merge its own pull request. Follow-ups, continuations, subagents and Sessions it starts keep the setting, and session_policy.pullRequestPolicy reports it: check it in the response, since a server that predates the field ignores it.
draft_only Explicit sandbox target. Requires devices:use. Cannot be combined with target or managed workspace ownership; unavailable targets are refused without falling back to cloud.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Whether stored secrets (workspace, Reason, personal and environment secrets) are injected into the Session's machine and tools. false runs it with none, for work that handles untrusted input; the Session's own env is still injected on cloud machines, since it is the caller's explicit input, not a stored secret (a connected Device gets none); repository access still works through Reason's own credential. Follow-ups, continuations and subagents keep the setting, and session_policy.components.secretInjection reports it. Not available in ephemeral mode (400 secret_injection_mode_unsupported).
The agent harness this Session runs; omit it for the default. getDeployment lists the profiles this workspace may name. runtime/reason-c2-tools-v7 is the default C2 harness (read, bash, edit, write and codemode tools) and runs in any mode; naming it changes nothing. runtime/reason-v7-2026-10 and runtime/reason-v7-2026-11 are frozen dated releases of that harness (as it ran in October 2026, and as cut on 2026-10-12), and runtime/reason-v8-2026-10 freezes its Bash-only variant (Bash and a script tool named reason, no read, edit or write, as cut on 2026-10-19); runtime/reason-v8.1-2026-10 is runtime/reason-v8-2026-10 with every Bash call yielding at its timeout (a command still running then returns its output so far and keeps running in the background), as cut on 2026-10-22; runtime/reason-v8.2-2026-10 is runtime/reason-v8.1-2026-10 without section zero's guideline to stop exploring after about 25 turns, as cut on 2026-10-24; runtime/reason-agent-1.2 (Reason Agent 1.2) is runtime/reason-v8.2-2026-10 under a standalone, dateless release name, sending and running exactly what it does, and never changes (a change ships as the next version); runtime/reason-agent-1.3 (Reason Agent 1.3) sends what runtime/reason-agent-1.2 sends and also runs output_cap_continue, image_history_append_only and cache_ttl_1h by default, as cut on 2026-10-27; so a result that names one names one harness; any organization may name them, in ephemeral mode. The dated releases run on a headless project_root or the user's own Device without a repository. A mode or target a profile does not support returns 400 runtime_profile_mode_unsupported or runtime_profile_target_unsupported, and a retired profile (the deleted sync-yield harness runtime/reason-v7-sync-yield-v1 and runtime/reason-v7-sync-yield-machine-sdk-v1, runtime/reason-capability-shell-v1, and v7's deleted evaluation profiles runtime/reason-v7-stock-prompt-v1, runtime/reason-v7-docs-v1, runtime/reason-v7-stock-shape-v1, runtime/reason-v7-bash-clean-v1 and runtime/reason-v7-bash-reason-v1) returns 400 runtime_profile_retired with a detail naming what to request instead.
runtime/reason-capability-shell-v1, runtime/reason-c2-tools-v7, runtime/reason-v7-sync-yield-v1, runtime/reason-v7-sync-yield-machine-sdk-v1, runtime/reason-v7-stock-prompt-v1, runtime/reason-v7-docs-v1, runtime/reason-v7-stock-shape-v1, runtime/reason-v7-bash-clean-v1, runtime/reason-v7-bash-reason-v1, runtime/reason-v7-2026-10, runtime/reason-v7-2026-11, runtime/reason-v8-2026-10, runtime/reason-v8.1-2026-10, runtime/reason-v8.2-2026-10, runtime/reason-agent-1.2, runtime/reason-agent-1.3 Reason features to run on top of the base harness, for an ephemeral Session of the default C2 harness or one of its dated releases; getDeployment lists them. Omit the field for the deployment's default set; an empty list runs the base harness alone. banner adds the untrusted-data notice on tool results, sdk_index Reason's tools in codemode, service_tier and output_cap the router's defaults, git_metadata Git diffs around tool calls, and serial_reads one physical call at a time. Experiments run only when named: recovery_defer_idle_hands starts the next model request while the machine reattaches after a deploy handoff with no tool call in flight. The prompt experiments fewer_tests_low, fewer_tests_medium, fewer_tests_high and fewer_tests_max are rungs of one ladder that add an addendum asking for progressively fewer new tests, each yielding to an instruction to write tests and allowing existing tests to run; fewer_tests_max_alone (the max rung without its verification line), verify_line_alone (that line alone) and addendum_placebo (an addendum asking for nothing) split the max rung into its parts. Naming two fewer-tests experiments returns 400 runtime_features_conflict. bash_yield and sync_bash are harness experiments that also run only when named: a Bash command still running after 60 seconds returns its output so far and keeps running in the background, its complete output written to a file; sync_bash also declares sync-yield's Bash (no timeout, a max_output_length head-and-tail bound). Naming bash_yield or sync_bash for runtime/reason-v8.1-2026-10, runtime/reason-v8.2-2026-10, runtime/reason-agent-1.2 or runtime/reason-agent-1.3, whose Bash already yields at its timeout, returns 400 runtime_features_conflict. turn_line_removed and turn_line_questions are prompt experiments for runtime/reason-v8-2026-10 and runtime/reason-v8.1-2026-10 only: the first drops the release's guideline to stop exploring after about 25 turns, the second keeps that guideline for questions about the code; naming both returns 400 runtime_features_conflict, and naming either for another profile (runtime/reason-v8.2-2026-10, runtime/reason-agent-1.2 and runtime/reason-agent-1.3 included, whose section zero has no such guideline) 400 runtime_features_profile_unsupported. output_cap_continue, image_history_append_only and cache_ttl_1h are harness experiments that run only when named (or by default on runtime/reason-agent-1.3) and change no prompt or tool declaration, for any profile that takes features: output_cap_continue asks a model request sent straight to Anthropic (a connected Anthropic key) for at most 64,000 output tokens, and continues a turn whose response the output cap cut without a tool call, at most three times in a row; image_history_append_only keeps earlier tool-result images in the history instead of only the newest five, and removes the oldest in one step only when a request would carry more than 20 images or 20 MiB of them; cache_ttl_1h writes the prompt cache of a model request sent straight to Anthropic with the one-hour TTL. Naming features replaces the release's default set, so name sdk_index with any of them to keep it. The Session keeps the list across deploy handoffs and continuations. Another mode returns 400 runtime_features_mode_unsupported, and another runtime profile 400 runtime_features_profile_unsupported.
21banner, sdk_index, service_tier, output_cap, git_metadata, serial_reads, recovery_defer_idle_hands, fewer_tests_low, fewer_tests_medium, fewer_tests_high, fewer_tests_max, fewer_tests_max_alone, verify_line_alone, addendum_placebo, bash_yield, sync_bash, turn_line_removed, turn_line_questions, output_cap_continue, image_history_append_only, cache_ttl_1h Deprecated: Projects are retired in favour of Reasons. Existing Project ID from GET /projects or POST /projects. The session is filed under that Project; a Project supplies no repository, machine, network hosts or target, which come only from repo and target.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Files the Session under this Reason (listReasons): one of yours, or one shared with you. It is listed under the Reason and, when repo is omitted, checks out the Reason's first default repository (its default_repositories on getReason). The same id as project_id: send either, or both with the same value (400 otherwise). Messaging the Reason (sendReasonMessage) instead lets the Reason decide how to do the work.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Explicit Hands machine target. Device targets require devices:use plus an owned, eligible root. Headless targets use externally provisioned compute and require the central relay; unavailable targets never fall back to cloud. A headless Device runs one Session at a time, a person's own computer (reason connect) every Session started on it, and any other personal headless worker (no Machine) as many as it advertises: while it is full, create returns 409 device_busy. A machine target (set exactly one of name or id) also requires devices:use; it runs on any eligible worker of that Machine with an externally-managed project_root workspace, and waits FIFO for a free worker (up to 30 minutes, or the execution budget) instead of failing when every worker is busy. It returns 409 machine_unavailable when the Machine has no online eligible worker.
- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes
Up to 10 attachments; maximum 64 MiB per file and 80 MiB total decoded bytes. The endpoint's request-body limit also applies to the encoded payload.
- Option 1
- Option 2
Show child attributes
Show child attributes
Optional initial connected GitHub repository path in owner/name form. Omit it for a scratch session, or, with project_id, for the Reason's first default repository when it has default repositories.
false: with project_id and no repo, start a scratch session instead of checking out the Reason's first default repository.
Source-control provider for the repo. GitHub is the only supported provider.
github The model the agent runs on, by an id listAgentModels returns. Omit it or send auto for the workspace default.
Optional reasoning effort override for the selected model.
minimal, low, medium, high, xhigh, max Physical execution policy. adaptive (default) starts with Brain and lazily acquires Hands when work needs a shell, files, browser, or sandbox. brain_only permanently forbids physical Hands and secret materialization for this Session and all of its continuation Attempts; independently created Sessions keep their own policy.
adaptive, brain_only Requests a durable noninteractive completion envelope. The agent may return success, failure, or action_required plus any JSON result; a run that stops without recording one reports action_required, never success. Executor/runtime failures remain separate lifecycle errors.
"run_outcome"Long-running Loop for this Session's first task: after the agent's first pass, extra rounds re-examine and continue the work, a reviewer checks it against derived acceptance criteria, and an end the reviewer cannot verify reports needs_review (with completion_mode: run_outcome, outcome failure). Follow-up messages run single passes. Requires a cloud Session with a repo in a workspace where the Loop is enabled; otherwise create returns 422 long_running_not_supported.
Show child attributes
Show child attributes
At most 50 tags; each tag is at most 100 UTF-8 bytes.
Existing branch to check out and work on; commits land on this branch. Created off the default branch if it does not exist yet. Mutually exclusive with pr_number and ref.
Continue an existing pull request: the agent checks out its head branch and commits back onto it (no new PR). GitHub only. Mutually exclusive with branch and ref.
x >= 1Commit SHA, tag, or branch to snapshot: the agent starts a fresh working branch from this ref and opens a new PR. Mutually exclusive with branch and pr_number.
Branch the Session's pull request targets. Alone, the Session starts from this branch's tip (ref defaults to it) and opens its PR against it. With ref, the Session starts from that ref, which stays the immutable checkout and publication base, and the PR targets this branch. Not combinable with branch or pr_number.
Session-scoped environment variables, injected into the agent's shell for this session only (and its follow-up turns). Names must match ^[A-Za-z_][A-Za-z0-9_]*$ and may not use reserved inference names; at most 64 keys, 32 KB per value, 256 KB total. Values override personal or workspace secrets of the same name, and are write-only (never returned by any read endpoint). On cloud machines they are injected with secret_injection false too, which turns off only stored secrets, so a Session can get one credential while inherited secrets stay off. A connected Device receives a session value only under a name whose stored secret allows Devices, so with secret_injection false it receives none. A value of 8 or more characters is masked in logs and transcripts where it appears verbatim or in a common encoding (reversed, base64, hex, URL-encoded, JSON-escaped); a value the agent transforms any other way is not masked, so do not rely on masking to keep a value from a Session that can read it.
Show child attributes
Show child attributes
A Session id the caller chose (UUID v4), typically the one passed to POST /sessions/prestart (predictive start): the new Session takes this id, and the machine prestarted under it when this same caller made that prestart. Without idempotency_key, a retried create with the same id returns the original session; an id already taken otherwise is 409 client_session_id_conflict.
Idempotent create: a retried POST with the same key and the same prompt returns the original session (HTTP 200) instead of creating a duplicate. Reusing the key with a different prompt returns 409 idempotency_key_conflict; use a new key for a new task.
Optional shared session spending ceiling in credits ($0.04 each), including models, machines and manual desktop time. Decimal string with up to nine fractional digits. Null retains wallet limits. Automatic delegated sessions share their source ceiling.
^(0|[1-9]\d{0,6})(\.\d{1,9})?$Deprecated: use spend_limit_credits. The same ceiling in the ledger's former unit (1 = $1/3, 8.33 credits). Sending both is refused unless they are equal.
^(0|[1-9]\d{0,6})(\.\d{1,9})?$When the Session's subscription or key runs out (a plan's usage limit, no credits left, a refused sign-in), the turn goes on with the same model on the provider's other connected accounts, then on Reason until the workspace's credits run out, instead of failing. Defaults to true when you are signed in as yourself (Reason CLI, TUI or an MCP sign-in) and to false with an API key, which keeps the exact model it named. Ephemeral benchmark Sessions never roll over.
Optional task authorization shared by automatic continuations and delegated sessions. New tasks have no deadline by default; zero explicitly selects no deadline. Positive durations range from one minute to 1,000 hours. Wall clock starts at execution admission and includes recovery waits. Spending reserves concurrent inference costs before dispatch; omitted/null spending retains account limits.
Show child attributes
Show child attributes
Before starting, Reason checks what the Session will be missing from what it already knows: connections (MCP servers and plugins) that are signed out, failed their last check or name a secret with no value, and, with require_ready: true only, secrets Sessions under its Reason asked for that still have none. The checks run beside the create and never delay it: by default the Session starts anyway and the response lists in warnings what the checks found by the time it was created, leaving out a check still running. true waits for the checks (at most 1.5 seconds) and refuses with 422 session_not_ready and the warnings when something is missing, creating nothing, so a headless caller fails fast; a check that cannot complete in that time never blocks the create. A repository the workspace cannot reach always fails with 400 repo_not_connected.
Response
Idempotent replay of the original session.
Deprecated: Projects are retired in favour of Reasons.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Lifecycle state, not task success: running, exit (execution completed), error (execution failed), or suspended (cancelled/quota; suspended_reason says which). An exit can have outcome failure or action_required. The task succeeded if and only if outcome is success; check outcome, result, and diagnostics before treating work as successful.
running, exit, error, suspended Server-resolved immutable Session policy. Enabled components remain subject to normal permissions and configuration.
Show child attributes
Show child attributes
The Reason the Session is filed under, or null for none. The same id as project_id.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$runtime/reason-sync-yield-v1 on a retired isolated Session that requested it through the retired runtime_profile field. Null otherwise.
"runtime/reason-sync-yield-v1"The runtime profile the Session's latest Attempt runs: the default C2 harness on every Session that runs it, whether or not its request named it (a Session of the retired runtime/reason-capability-shell-v1 continues on it) — reported as runtime/reason-c2-tools-v7; runtime/reason-v7-sync-yield-v1 or runtime/reason-v7-sync-yield-machine-sdk-v1 on a stored Session of that retired harness; runtime/reason-v7-2026-10, runtime/reason-v7-2026-11, runtime/reason-v8-2026-10, runtime/reason-v8.1-2026-10, runtime/reason-v8.2-2026-10, runtime/reason-agent-1.2 or runtime/reason-agent-1.3 on a Session that runs it; a Session of a deleted v7 evaluation profile reports the default C2 harness, which it re-admits to. Null otherwise.
runtime/reason-c2-tools-v7, runtime/reason-v7-sync-yield-v1, runtime/reason-v7-sync-yield-machine-sdk-v1, runtime/reason-v7-2026-10, runtime/reason-v7-2026-11, runtime/reason-v8-2026-10, runtime/reason-v8.1-2026-10, runtime/reason-v8.2-2026-10, runtime/reason-agent-1.2, runtime/reason-agent-1.3 The runtime features the Session's create named (experimental_runtime_features), in canonical order. Null when it named none.
banner, sdk_index, service_tier, output_cap, git_metadata, serial_reads, recovery_defer_idle_hands, fewer_tests_low, fewer_tests_medium, fewer_tests_high, fewer_tests_max, fewer_tests_max_alone, verify_line_alone, addendum_placebo, bash_yield, sync_bash, turn_line_removed, turn_line_questions, output_cap_continue, image_history_append_only, cache_ttl_1h The concrete model the Session was admitted with, after Auto and any model rollover resolved it; the same value Retrieve a session reports as model. Null when no session was created.
The reasoning effort the Session runs with; null when none was set.
Whether model rollover is in effect for this Session: true when a run-out subscription or key may continue the turn on another connected account or on Reason (see allow_model_rollover on the request), false when the Session keeps the exact model it named.
True when a usage limit or outage already moved this first turn off the account it would otherwise use, onto another connected account or Reason credits, for the same model. It reports admission only; later rollovers are not reflected here.
What the new Session will be missing, found by the checks that finished before it was created (see require_ready); the Session started anyway. Absent when nothing is known to be missing; send require_ready: true for the complete check. A replay of an earlier create reports none.
Show child attributes
Show child attributes