Create a session

Opens a new session from a prompt. Optional project_id binds an accessible existing Project and pins its instructions. Use GET /projects to discover IDs; repo and target remain explicit selections and must be compatible with that Project. 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.

_{Scope: run}

POST /v3/organizations/{orgId}/sessions

Create a session

cURL

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"
  ]
}
'

200

Example

{
  "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"
  },
  "runtime_profile": "runtime/reason-sync-yield-v1",
  "experimental_runtime_profile": "runtime/reason-c2-tools-v7",
  "experimental_runtime_features": [
    "banner"
  ]
}

Authorizations

Authorization · string · header · required

Your Reason API key from Settings > API. 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, automations:read, automations:write, agent_auth:read. 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).

Path Parameters

orgId · string · required

Organization id or slug. Resolve it with GET /v3/self.

Body

application/json

prompt · string · required

What the agent should do. Maximum 256 KiB when UTF-8 encoded.

mode · enum<string>

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

Available options: standard, ephemeral

workspace_ownership · enum<string>

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.

Available options: managed, externally-managed, ara-managed

experimental_runtime_profile · enum<string>

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 stock Pi 1.0's own 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-capability-shell-v1 is retired and refused with 400 runtime_profile_retired.

Available options: 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

experimental_runtime_features · enum<string>[]

The Reason features an ephemeral Session of the default C2 harness runs on top of stock Pi 1.0, 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. An empty list runs stock Pi 1.0'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).

Maximum array length: 7

Available options: banner, sdk_index, service_tier, output_cap, git_metadata, serial_reads, recovery_defer_idle_hands

project_id · string<uuid>

Existing Project ID from GET /projects or POST /projects. Sessions pin its instructions. Repository and machine selection remain explicit through repo and target.

Pattern: ^([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)$

target · object

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: while it is running another, 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

repo · string

Optional initial connected GitHub repository path in owner/name form. Omit it for a scratch session.

provider · enum<string>

Source-control provider for the repo. GitHub is the only supported provider.

Available options: github

model · string

Concrete model id from GET /agent-auth/models. Omit or use auto to inherit the workspace default.

reasoning_effort · enum<string>

Optional reasoning effort override for the selected model.

Available options: minimal, low, medium, high, xhigh, max

hands_mode · enum<string>

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.

Available options: adaptive, brain_only

completion_mode · string

Requests a durable noninteractive completion envelope. The agent may return success, failure, or action_required plus any JSON result; executor/runtime failures remain separate lifecycle errors.

Allowed value: "run_outcome"

tags · string[]

At most 50 tags; each tag is at most 100 UTF-8 bytes.

branch · string

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.

pr_number · integer

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.

Required range: x >= 1

ref · string

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.

base_branch · string

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.

env · object

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 write-only (never returned by any read endpoint), and are redacted from logs and transcripts.

Show child attributes

idempotency_key · string

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.

spend_limit_rcu · string | null

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.

Pattern: ^(0|[1-9]\d{0,6})(\.\d{1,9})?$

execution_budget · object

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

Response

200

application/json

Idempotent replay of the original session.

session_id · string | null · required

project_id · string<uuid> | null · required

Pattern: ^([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)$

url · string | null · required

status · enum<string> · required

Lifecycle state, not task success: running, exit (execution completed), error (execution failed), or suspended (cancelled/quota). An exit can have outcome failure or action_required. Check outcome, result, and diagnostics before treating work as successful.

Available options: running, exit, error, suspended

session_policy · object · required

Server-resolved immutable Session policy. Enabled components remain subject to normal permissions and configuration.

Show child attributes

runtime_profile · string | null

runtime/reason-sync-yield-v1 on a retired isolated Session that requested it through the retired runtime_profile field. Null otherwise.

Allowed value: "runtime/reason-sync-yield-v1"

experimental_runtime_profile · enum<string> | null

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 or runtime/reason-v7-docs-v1 on a Session that runs it. Null otherwise.

Available options: 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

experimental_runtime_features · enum<string>[] | null

The runtime features the Session's create named (experimental_runtime_features), in canonical order. Null when it named none.

Available options: banner, sdk_index, service_tier, output_cap, git_metadata, serial_reads, recovery_defer_idle_hands