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.
<sub>Scope: run</sub>
Request
- Base URL: https://api.reasonmachines.com
- URL: https://api.reasonmachines.com/v3/organizations/{orgId}/sessions
- Auth: HTTP bearer
Headers
Optional self-reported caller agent name. If absent, the server uses the User-Agent for external callers.
Request body
Defaults to standard for normal workflows, including API sessions targeting a local Mac. Standard retains configured capabilities and supports follow-up messages. Ephemeral runs a benchmark trial with the standard capabilities inside a single-use workspace from createEphemeralWorkspace: it requires that workspace, an externally-managed headless project_root and an idempotency_key, disables follow-up messages, and the workspace admits no other Session. The isolated mode is retired (400 session_mode_retired), and so are the benchmark_profile field (400 benchmark_profile_retired) and the runtime_profile field (400 runtime_profile_retired).
Filesystem persistence owner, independent of mode. Externally-managed requires an explicit headless project_root. Defaults to managed. ara-managed is a deprecated spelling of managed; responses report managed.
Runtime profile request, listed per organization by GET /deployment. runtime/reason-c2-tools-v7 (the default C2 harness: read, bash, edit, write and codemode tools) runs every Session in any mode; every organization may name it, and it is accepted for compatibility without changing the default. runtime/reason-v7-sync-yield-v1 (exactly Bash and ViewImage; Reason's tools through handsctl commands in Bash) is an allowlisted evaluation runtime (403 runtime_profile_not_enabled otherwise; an ephemeral workspace qualifies through its parent): standard or ephemeral mode only (400 runtime_profile_mode_unsupported), on a headless project_root or the user's own Device without a repository (400 runtime_profile_target_unsupported). Its follow-ups, subagents and side chats keep it. runtime/reason-v7-sync-yield-machine-sdk-v1 is the same with Reason's tools through reason-sdk, a command on the machine that composes in shell, on its own allowlist and in ephemeral mode only. runtime/reason-v7-stock-prompt-v1 (the default C2 harness sending the base harness's own unmodified system prompt and codemode description) and runtime/reason-v7-docs-v1 (the default C2 harness with a section naming Reason's documentation) are prompt evaluation runtimes on their own allowlist, under the same mode and target rules as runtime/reason-v7-sync-yield-machine-sdk-v1; they accept experimental_runtime_features. runtime/reason-v7-2026-10 is a dated release: the default C2 harness as it ran in October 2026, frozen, so a result that names it names one harness; every organization may name it, in ephemeral mode only and under the same target rules, and it accepts experimental_runtime_features. runtime/reason-v7-2026-11 is the next dated release, under the same rules: the default C2 harness as it ran when it was cut on 2026-10-12, frozen. runtime/reason-capability-shell-v1 is retired and refused with 400 runtime_profile_retired.
The Reason features an ephemeral Session of the default C2 harness runs on top of the base harness, listed by GET /deployment: banner (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). recovery_defer_idle_hands is an experiment that runs only when named here, never by default: after a deploy handoff with no tool call in flight, the next model request starts while the machine reattaches. fewer_tests_low, fewer_tests_medium, fewer_tests_high and fewer_tests_max are prompt experiments that also run only when named: rungs of one ladder asking for progressively fewer new tests, each yielding to an instruction to write tests and allowing existing tests to run, added as the base prompt's addendum section. 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. A create names at most one of these (400 runtime_features_conflict). An empty list runs the base harness's shape; omitting the field runs the deployment's default set. The Session keeps the list across deploy handoffs and continuations. Ephemeral mode only (400 runtime_features_mode_unsupported), and only with the default C2 harness or its prompt evaluation runtimes (400 runtime_features_profile_unsupported).
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.
What the agent should do. Maximum 256 KiB when UTF-8 encoded.
Optional initial connected GitHub repository path in owner/name form. Omit it for a scratch session.
Source-control provider for the repo. GitHub is the only supported provider.
Concrete model id from GET /agent-auth/models. Omit or use auto to inherit the workspace default.
Optional reasoning effort override for the selected model.
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.
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.
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.
Commit 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.
Pull-request base branch for a ref snapshot. Use this when the snapshot belongs to a non-default integration branch. Valid only with ref; the resolved ref remains the immutable checkout and publication base.
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, are and are write-only (never returned by any read endpoint). 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.
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 RCUs, 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.
Response
Idempotent replay of the original session.
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.
runtime/reason-sync-yield-v1 on a retired isolated Session that requested it through the retired runtime_profile field. Null otherwise.
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 on a standard or ephemeral Session that runs it; runtime/reason-v7-sync-yield-machine-sdk-v1, runtime/reason-v7-stock-prompt-v1, runtime/reason-v7-docs-v1, runtime/reason-v7-2026-10 or runtime/reason-v7-2026-11 on a Session that runs it. Null otherwise.
The runtime features the Session's create named (experimental_runtime_features), in canonical order. Null when it named none.
Changes
No recorded changes to this operation across all 1 revision of this API.