> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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, Ara 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`
## OpenAPI
````yaml /openapi.json post /v3/organizations/{orgId}/sessions
openapi: 3.1.0
info:
title: Reason Machines API
version: 3.0.0
description: >-
The Reason HTTP API. Drive cloud software-engineering agents: open sessions
against your repositories, stream their work, and manage the secrets,
knowledge, skills, and automations they run with.
Authenticate with a Reason API key sent as a bearer token. New keys use
`reason_`; legacy `ara_` keys remain accepted. Every resource is scoped to
an organization; resolve your `org_id` once with `GET /v3/self`.
servers:
- url: https://api.reasonmachines.ai
security:
- araApiKey: []
tags:
- name: Devices
description: >-
Owned Mac and headless Device identity, bounded enrollment and root
grants.
- name: Account
description: Verify a key and resolve the organization it belongs to.
- name: Projects
description: >-
Discover existing workspace projects to target when creating and listing
sessions.
- name: Sessions
description: >-
A session is one run of an agent against a repository: it reproduces the
task, writes the code, verifies it, and opens a pull request or merge
request.
- name: Secrets
description: >-
Encrypted credentials injected into the agent's sandbox. Write-only:
values can be set but never read back.
- name: Knowledge
description: Durable notes the agent consults while it works.
- name: Memory
description: >-
Editable repository notes that are projected into native memory; generated
memory remains read-only.
- name: Skills
description: >-
Reusable instruction bundles Reason selects semantically from their
descriptions for matching agent tasks.
- name: Automations
description: Recurring or one-time triggers that open sessions on a timetable.
- name: Change Request Reviews
description: >-
Automated senior-engineer reviews posted on pull requests and merge
requests.
- name: Repositories
description: Connected repositories, their indexing state, and generated wikis.
- name: Git Connections
description: Linked source-control accounts and the repositories they expose.
- name: Consumption
description: 'Billing-aligned usage: daily consumption and billing cycles.'
- name: Metrics
description: Aggregate analytics over sessions, change requests, and usage.
- name: Audit Logs
description: An append-only record of changes made within the organization.
- name: Organizations
description: The top-level tenant. Create, read, update, and delete organizations.
- name: Members
description: People in an organization and their pending invites.
- name: Service Users
description: Machine principals that own API keys for headless access.
- name: Roles
description: Role assignments that govern what each member can do.
- name: Attachments
description: >-
Files uploaded to the organization and shared with sessions, downloaded
via short-lived signed URLs.
- name: Guardrails
description: >-
Per-repository automation limits and the violations recorded when a limit
is hit.
- name: MCP Servers
description: >-
Org-level Model Context Protocol servers exposed to the agent. Secret
values are write-only.
- name: Settings
description: 'Organization configuration: namespaced settings and the run tag policy.'
- name: Blueprints
description: >-
Read-only declarative manifests of an organization's agents (identity, run
config, triggers, suite), with credentials redacted.
- name: IP Access List
description: >-
Source-network allow-list that, when enabled, restricts the organization's
API surface to a set of CIDR ranges.
- name: Groups
description: Manually-curated member groups carrying optional per-day resource limits.
- name: Provider Credentials
description: >-
Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials
for model providers. Secret values are write-only.
paths:
/v3/organizations/{orgId}/sessions:
parameters:
- $ref: '#/components/parameters/orgId'
post:
tags:
- Sessions
summary: Create a session
description: >-
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, Ara
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`
operationId: createSession
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSession'
example:
prompt: >-
Fix the flaky test in src/auth/session.test.ts and add a
regression case.
repo: acme/web
provider: github
tags:
- ci
- tests
responses:
'200':
description: Idempotent replay of the original session.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionCreateResponse'
'201':
description: Session created and queued.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionCreateResponse'
example:
session_id: ses_91af3c
project_id: null
url: https://reasonmachines.com/agents/ses_91af3c
status: running
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: Quota exhausted for the billing account.
content:
application/json:
example:
error: quota_exhausted
message: Monthly sandbox minutes exceeded.
'403':
description: Project or selected resource access is forbidden.
'404':
description: Project not found or not accessible to this principal.
'409':
description: >-
Project execution target is incompatible, or the idempotency key
belongs to another project or target.
'503':
description: >-
Temporarily unable to create the session: model credential preflight
could not be completed, or `env` was supplied while the deployment's
secret store is unavailable (`secret_store_unavailable`).
security:
- araApiKey:
- run
components:
parameters:
orgId:
name: orgId
in: path
required: true
description: Organization id or slug. Resolve it with `GET /v3/self`.
schema:
type: string
schemas:
CreateSession:
type: object
properties:
mode:
type: string
enum:
- standard
- isolated
description: >-
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.
workspace_ownership:
type: string
enum:
- ara-managed
- externally-managed
description: >-
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.
benchmark_profile:
type: string
const: coding-benchmark-v1
description: >-
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.
project_id:
type: string
format: uuid
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)$
description: >-
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.
target:
oneOf:
- type: object
properties:
kind:
type: string
const: cloud
required:
- kind
additionalProperties: false
- type: object
properties:
kind:
type: string
const: mac
device_id:
type: string
format: uuid
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)$
root_id:
type: string
format: uuid
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)$
required:
- kind
- device_id
- root_id
additionalProperties: false
- type: object
properties:
kind:
type: string
const: headless
device_id:
type: string
format: uuid
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)$
root_id:
type: string
format: uuid
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)$
workspace_mode:
description: >-
Defaults to a stable Session-managed checkout. project_root
explicitly operates the selected existing root.
type: string
enum:
- managed
- project_root
required:
- kind
- device_id
- root_id
additionalProperties: false
description: >-
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.
prompt:
type: string
description: What the agent should do. Maximum 256 KiB when UTF-8 encoded.
repo:
type: string
description: >-
Optional initial connected GitHub repository path in `owner/name`
form. Omit it for a scratch session.
provider:
type: string
enum:
- github
description: >-
Source-control provider for the repo. GitHub is the only supported
provider.
model:
type: string
description: >-
Concrete model id from `GET /agent-auth/models`. Omit or use `auto`
to inherit the workspace default.
reasoning_effort:
type: string
enum:
- minimal
- low
- medium
- high
- xhigh
- max
description: Optional reasoning effort override for the selected model.
hands_mode:
type: string
enum:
- adaptive
- brain_only
description: >-
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.
completion_mode:
type: string
const: run_outcome
description: >-
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.
tags:
type: array
items:
type: string
description: At most 50 tags; each tag is at most 100 UTF-8 bytes.
branch:
type: string
description: >-
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:
type: integer
minimum: 1
description: >-
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`.
ref:
type: string
description: >-
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:
type: string
description: >-
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:
type: object
additionalProperties:
type: string
description: >-
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:
type: string
description: >-
Idempotent create: a retried POST with the same key returns the
original session instead of creating a duplicate.
execution_budget:
type: object
properties:
wall_clock_max_ms:
type: integer
minimum: 0
maximum: 3600000000
spend_limit_usd:
type:
- number
- 'null'
minimum: 0
maximum: 1000000
description: >-
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.
required:
- prompt
SessionCreateResponse:
type: object
properties:
session_id:
type: string
project_id:
description: Project containing the session, or null for an unassigned session.
type:
- string
- 'null'
format: uuid
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:
type: string
description: Web URL to watch the session.
status:
type: string
enum:
- running
- exit
- error
- suspended
description: running, exit (completed), error, or suspended (cancelled/quota).
session_policy:
type: object
properties:
version:
type: number
const: 1
mode:
type: string
enum:
- standard
- isolated
components:
type: object
properties:
memoryRead:
type: boolean
memoryWrite:
type: boolean
skills:
type: boolean
inheritedInstructions:
type: boolean
integrations:
type: boolean
secretInjection:
type: boolean
required:
- memoryRead
- memoryWrite
- skills
- inheritedInstructions
- integrations
- secretInjection
workspaceOwnership:
type: string
enum:
- ara-managed
- externally-managed
required:
- version
- mode
- components
- workspaceOwnership
description: >-
Server-resolved immutable Session policy. Enabled components remain
subject to normal permissions and configuration.
required:
- session_policy
Error:
type: object
properties:
error:
type: string
message:
type: string
required_scope:
type: string
description: >-
The capability required when the request was denied for a missing
scope.
responses:
BadRequest:
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: prompt_required
Unauthorized:
description: Missing, invalid, or expired key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unauthorized
securitySchemes:
araApiKey:
type: http
scheme: bearer
bearerFormat: 'reason_ (legacy: ara_)'
description: >-
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.
````