Skip to main content
POST
Create a session

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:debug is privileged: it expands diagnostic session events only for organization owners/admins.

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>

Session component preset. Standard retains configured capabilities; isolated removes ambient memory, skills, instructions, integrations, and secret injection. Defaults to standard unless the legacy benchmark profile is supplied.

Available options:
standard,
isolated
workspace_ownership
enum<string>

Filesystem persistence owner, independent of mode. Externally-managed requires an explicit headless project_root. Defaults to ara-managed unless the legacy benchmark profile is supplied.

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

Coding-only trial on an explicit headless project_root. Disables durable memory, skills, external tools, inherited secrets, and additional messages. Each trial requires a fresh Session. The externally managed ephemeral workspace is never captured or restored by Ara; current-trial conversation and compaction are retained.

Allowed value: "coding-benchmark-v1"
project_id
string<uuid>

Existing Project ID from GET /projects or POST /projects. Standard sessions pin its instructions. Isolated externally-managed headless project_root sessions may use a resource-free project for grouping only; inherited instructions and durable learning stay disabled. 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.

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.

idempotency_key
string

Idempotent create: a retried POST with the same key returns the original session instead of creating a duplicate.

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.

Response

Idempotent replay of the original session.

session_policy
object
required

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

session_id
string
project_id
string<uuid> | null

Project containing the session, or null for an unassigned session.

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

Web URL to watch the session.

status
enum<string>

running, exit (completed), error, or suspended (cancelled/quota).

Available options:
running,
exit,
error,
suspended