> ## 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.
# Submit deterministic work on a granted Device
> Submits deterministic work to an authorized Device and returns a durable job receipt. Acceptance does not mean execution has started. No reasoning Session is created.
Scope: `jobs:execute`
## OpenAPI
````yaml /openapi.json post /v3/organizations/{orgId}/jobs
openapi: 3.1.0
info:
title: Reason 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,
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.com
security:
- reasonApiKey: []
tags:
- name: Account
description: Verify a key and resolve the organization it belongs to.
- name: Reasons
description: >-
Start here. A Reason is the long-running agent a person keeps: their main
Reason and named ones, each with its own instructions, default model and
repositories, conversation, Loops and Sessions. Give a Reason work by
messaging it (sendReasonMessage) and read its replies with
listReasonMessages.
- name: Loops
description: >-
Standing work a Reason does, woken by a schedule or an event: a webhook, a
GitHub event or a Slack message. Each wake opens or continues a Session of
the Reason; webhook events that share a correlation key continue one
Session.
- name: Memory
description: >-
What Reasons remember across Sessions. Each Session starts by reading
MEMORY.md (a short index) and the list of topic notes, and reads a note
when its topic comes up. `personal` memory belongs to one person (the API
key's owner) and only their Sessions read it; `team` memory belongs to the
Workspace and every member's Sessions read it. memory:read lists, reads
and searches; memory:write writes and deletes, in team memory only for a
Workspace owner or admin.
- name: Sessions
description: >-
A Session is one run of work inside a Reason: every Reason message and
Loop wake runs in one, and createSession starts one directly for a single
unattended task with a pass/fail outcome. Its transcript, events, result
and pull request are read here.
- name: Skills
description: >-
Reusable instruction bundles Reason selects semantically from their
descriptions for matching agent tasks.
- name: Secrets
description: >-
Encrypted credentials injected into the agent's sandbox. Write-only:
values can be set but never read back.
- name: Attachments
description: >-
Files uploaded to the organization and shared with sessions, downloaded
via short-lived signed URLs.
- 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: Machines
description: >-
Named Workspace queues served by headless workers. Sessions target a
Machine by name and wait for a free worker; more workers serve more
Sessions concurrently.
- name: Devices
description: >-
Owned Mac and headless Device identity, bounded enrollment and root
grants.
- name: Cloud Access
description: >-
Keyless cloud sign-in for sessions: Reason's OIDC issuer facts and the
AWS, Google Cloud and Azure connections a workspace trusts, including
which run triggers each one signs in.
- name: MCP Servers
description: >-
Org-level Model Context Protocol servers exposed to the agent. Secret
values are write-only.
- name: Change Request Reviews
description: >-
Automated senior-engineer reviews posted on pull requests and merge
requests.
- 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: Roles
description: Role assignments that govern what each member can do.
- name: Settings
description: 'Organization configuration: namespaced settings and the run tag policy.'
- name: Provider credentials
description: >-
Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials
for model providers. Secret values are write-only.
- name: Feedback
description: Report problems with the API or these docs to the Reason team.
- name: Projects
description: >-
Deprecated: a project is a Reason with the same id. Use the Reasons
operations; these remain for existing clients.
- name: Automations
description: >-
The older form of Loops. Prefer the Loops under a Reason (listReasonLoops,
createReasonLoop), which take every wake: schedule, webhook, GitHub,
Slack. Use these for what Loops do not carry yet: a run's MCP and app
tools, and automations not filed under a Reason.
paths:
/v3/organizations/{orgId}/jobs:
parameters:
- $ref: '#/components/parameters/orgId'
post:
tags:
- Jobs
summary: Submit deterministic work on a granted Device
description: >-
Submits deterministic work to an authorized Device and returns a durable
job receipt. Acceptance does not mean execution has started. No
reasoning Session is created.
Scope: `jobs:execute`
operationId: submitDirectJob
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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)$
mode:
type: string
enum:
- confined
- host
operation:
oneOf:
- type: object
properties:
kind:
type: string
const: command
command:
type: string
minLength: 1
maxLength: 65536
cwd:
default: .
type: string
minLength: 1
maxLength: 4096
timeout_ms:
default: 15000
type: integer
minimum: 100
maximum: 60000
required:
- kind
- command
additionalProperties: false
- type: object
properties:
kind:
type: string
const: files.read
path:
type: string
minLength: 1
maxLength: 4096
offset:
default: 0
type: integer
minimum: 0
max_bytes:
default: 65536
type: integer
minimum: 1
maximum: 131072
required:
- kind
- path
additionalProperties: false
- type: object
properties:
kind:
type: string
const: files.write
path:
type: string
minLength: 1
maxLength: 4096
content:
type: string
maxLength: 131072
mode:
default: create
type: string
enum:
- create
- overwrite
- append
required:
- kind
- path
- content
additionalProperties: false
- type: object
properties:
kind:
type: string
const: terminal.open
cwd:
default: .
type: string
minLength: 1
maxLength: 4096
columns:
default: 80
type: integer
minimum: 1
maximum: 500
rows:
default: 24
type: integer
minimum: 1
maximum: 300
required:
- kind
additionalProperties: false
- type: object
properties:
kind:
type: string
const: terminal.input
terminal_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)$
sequence:
type: integer
minimum: 0
data:
type: string
maxLength: 8192
required:
- kind
- terminal_id
- sequence
- data
additionalProperties: false
- type: object
properties:
kind:
type: string
const: terminal.output
terminal_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)$
after:
default: 0
type: integer
minimum: 0
required:
- kind
- terminal_id
additionalProperties: false
- type: object
properties:
kind:
type: string
const: terminal.resize
terminal_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)$
sequence:
type: integer
minimum: 0
columns:
type: integer
minimum: 1
maximum: 500
rows:
type: integer
minimum: 1
maximum: 300
required:
- kind
- terminal_id
- sequence
- columns
- rows
additionalProperties: false
- type: object
properties:
kind:
type: string
const: artifacts.upload_checkpoint
artifact_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)$
source_path:
type: string
minLength: 1
maxLength: 4096
required:
- kind
- artifact_id
- source_path
additionalProperties: false
- type: object
properties:
kind:
type: string
const: artifacts.export
path:
type: string
minLength: 1
maxLength: 4096
max_bytes:
default: 131072
type: integer
minimum: 1
maximum: 131072
required:
- kind
- path
additionalProperties: false
- type: object
properties:
kind:
type: string
const: terminal.close
terminal_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
- terminal_id
additionalProperties: false
- type: object
properties:
kind:
type: string
const: browser.click
browser_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)$
selector:
type: string
minLength: 1
maxLength: 1024
required:
- kind
- browser_id
- selector
additionalProperties: false
- type: object
properties:
kind:
type: string
const: browser.fill
browser_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)$
selector:
type: string
minLength: 1
maxLength: 1024
value:
type: string
maxLength: 8192
required:
- kind
- browser_id
- selector
- value
additionalProperties: false
- type: object
properties:
kind:
type: string
const: browser.press
browser_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)$
selector:
type: string
minLength: 1
maxLength: 1024
key:
type: string
minLength: 1
maxLength: 128
required:
- kind
- browser_id
- selector
- key
additionalProperties: false
- type: object
properties:
kind:
type: string
const: computer.list
required:
- kind
additionalProperties: false
- type: object
properties:
kind:
type: string
const: computer.snapshot
app:
type: string
minLength: 1
maxLength: 256
required:
- kind
- app
additionalProperties: false
- type: object
properties:
kind:
type: string
const: computer.act
snapshot_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)$
action:
oneOf:
- type: object
properties:
kind:
type: string
const: click_pixel
x:
type: integer
minimum: 0
maximum: 8192
'y':
type: integer
minimum: 0
maximum: 8192
required:
- kind
- x
- 'y'
additionalProperties: false
- type: object
properties:
kind:
type: string
const: click_element
element_index:
type: integer
minimum: 0
maximum: 9999
role:
type: string
minLength: 1
maxLength: 128
required:
- kind
- element_index
- role
additionalProperties: false
- type: object
properties:
kind:
type: string
const: type_text
text:
type: string
maxLength: 8192
required:
- kind
- text
additionalProperties: false
- type: object
properties:
kind:
type: string
const: key_press
key:
type: string
minLength: 1
maxLength: 128
required:
- kind
- key
additionalProperties: false
required:
- kind
- snapshot_id
- action
additionalProperties: false
- type: object
properties:
kind:
type: string
const: browser.navigate
browser_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)$
url:
type: string
maxLength: 4096
format: uri
required:
- kind
- browser_id
- url
additionalProperties: false
- type: object
properties:
kind:
type: string
const: browser.open
allowed_domains:
default: []
maxItems: 64
type: array
items:
type: string
minLength: 1
maxLength: 253
required:
- kind
additionalProperties: false
- type: object
properties:
kind:
type: string
const: browser.snapshot
browser_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
- browser_id
additionalProperties: false
- type: object
properties:
kind:
type: string
const: browser.screenshot
browser_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
- browser_id
additionalProperties: false
- type: object
properties:
kind:
type: string
const: browser.close
browser_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
- browser_id
additionalProperties: false
- type: object
properties:
kind:
type: string
const: preview.open
job_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)$
port:
type: integer
minimum: 1
maximum: 65535
required:
- kind
- job_id
- port
additionalProperties: false
- type: object
properties:
kind:
type: string
const: preview.request
preview_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)$
path:
type: string
minLength: 1
maxLength: 4096
pattern: ^\/(?!\/)
required:
- kind
- preview_id
- path
additionalProperties: false
- type: object
properties:
kind:
type: string
const: preview.close
preview_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
- preview_id
additionalProperties: false
delegation:
type: object
properties:
operations:
minItems: 1
maxItems: 32
type: array
items:
type: object
properties:
operation_id:
type: string
minLength: 1
maxLength: 160
path:
type: string
minLength: 1
maxLength: 2048
query:
default: {}
type: object
additionalProperties:
type: string
body: {}
resource:
oneOf:
- type: object
properties:
kind:
type: string
const: own_invocations
required:
- kind
additionalProperties: false
- type: object
properties:
kind:
type: string
const: own_job
required:
- kind
additionalProperties: false
- type: object
properties:
kind:
type: string
const: tool
connection_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)$
tool_name:
type: string
minLength: 1
maxLength: 256
schema_digest:
type: string
pattern: ^[a-f0-9]{64}$
connection_revision:
type: string
minLength: 1
maxLength: 256
required:
- kind
- connection_id
- tool_name
- schema_digest
- connection_revision
additionalProperties: false
- type: object
properties:
kind:
type: string
const: memory
scope:
type: string
enum:
- personal
- team
path:
type: string
minLength: 1
maxLength: 512
required:
- kind
- scope
additionalProperties: false
- type: object
properties:
kind:
type: string
const: repository
repository:
type: string
pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$
required:
- kind
- repository
additionalProperties: false
max_calls:
default: 1
type: integer
minimum: 1
maximum: 1000
required:
- operation_id
- path
additionalProperties: false
required:
- operations
additionalProperties: false
expected_root_grant_revision:
type: integer
exclusiveMinimum: 0
expected_direct_access_revision:
type: integer
minimum: 0
expected_root_path_fingerprint:
type: string
minLength: 1
maxLength: 256
context_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)$
idempotency_key:
type: string
minLength: 1
maxLength: 200
required:
- device_id
- root_id
- mode
- operation
- idempotency_key
additionalProperties: false
responses:
'202':
description: Durable job accepted; execution has not necessarily started.
content:
application/json:
schema:
type: object
properties:
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)$
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)$
context_id:
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)$
mode:
type: string
enum:
- confined
- host
status:
type: string
enum:
- queued
- running
- succeeded
- failed
- cancelled
- expired
- outcome_unknown
error_code:
type:
- string
- 'null'
cleanup:
type: string
enum:
- pending
- confirmed
- unknown
- retained
created_at:
type: string
expires_at:
type: string
required:
- id
- device_id
- root_id
- context_id
- mode
- status
- error_code
- cleanup
- created_at
- expires_at
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
security:
- reasonApiKey:
- jobs:execute
components:
parameters:
orgId:
name: orgId
in: path
required: true
description: Organization id or slug. Resolve it with `GET /v3/self`.
schema:
type: string
responses:
Unauthorized:
description: Missing, invalid, or expired key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: missing_bearer
message: Authorization required
Forbidden:
description: The key lacks the required scope or role.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: missing_scope
required_scope: sessions:read
RateLimited:
description: >-
Too many requests. Retry after the number of seconds in the
`Retry-After` response header.
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
minimum: 1
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: rate_limited
message: This API key exceeded its request-rate limit
schemas:
Error:
type: object
properties:
error:
oneOf:
- type: string
- type: object
required:
- type
- message
properties:
type:
type: string
message:
type: string
request_id:
type:
- string
- 'null'
message:
type: string
required_scope:
type: string
description: >-
The capability required when the request was denied for a missing
scope.
securitySchemes:
reasonApiKey:
type: http
scheme: bearer
bearerFormat: 'reason_ (legacy: ara_)'
description: >-
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).
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.