> ## 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.
# List a Reason's computers
> Lists the computers available to the caller for a Reason, with the same personal visibility, sharing and connected-computer selection rules as the app. Requires the opt-in computers:read scope. Returns 404 when the caller cannot start Sessions under this Reason. In the workspace resource model this includes eligible shared workspace cloud computers. Cloud live distinguishes awake from parked; connected state describes availability. Listing does not grant physical execution permission or wake computers.
Scope: `computers:read`
## OpenAPI
````yaml /openapi.json get /v3/organizations/{orgId}/reasons/{reasonId}/computers
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}/reasons/{reasonId}/computers:
parameters:
- $ref: '#/components/parameters/orgId'
- name: reasonId
description: The Reason id, returned as `id` by `listReasons` and `createReason`.
in: path
required: true
schema:
type: string
format: uuid
get:
tags:
- Computers
summary: List a Reason's computers
description: >-
Lists the computers available to the caller for a Reason, with the same
personal visibility, sharing and connected-computer selection rules as
the app. Requires the opt-in computers:read scope. Returns 404 when the
caller cannot start Sessions under this Reason. In the workspace
resource model this includes eligible shared workspace cloud computers.
Cloud live distinguishes awake from parked; connected state describes
availability. Listing does not grant physical execution permission or
wake computers.
Scope: `computers:read`
operationId: listReasonComputers
responses:
'200':
description: The Reason's computer inventory for the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/ComputersList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
security:
- reasonApiKey:
- computers:read
components:
parameters:
orgId:
name: orgId
in: path
required: true
description: Organization id or slug. Resolve it with `GET /v3/self`.
schema:
type: string
schemas:
ComputersList:
type: object
properties:
computers:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
kind:
type: string
enum:
- cloud
- mac
- cli
- worker
reason_id:
type:
- string
- 'null'
size:
oneOf:
- type: string
enum:
- s
- m
- l
- xl
- type: 'null'
os:
type:
- string
- 'null'
state:
type: string
enum:
- ready
- starting
- busy
- offline
live:
type: boolean
unavailable_reason:
oneOf:
- type: string
enum:
- offline
- protocol_unsupported
- worker_update_required
- execution_ineligible
- file_access_only
- revoked
- type: 'null'
this_session:
type: boolean
sessions:
type: array
items:
type: object
properties:
session_id:
type: string
title:
type:
- string
- 'null'
turn_running:
type: boolean
required:
- session_id
- title
- turn_running
additionalProperties: false
rcu_per_hour:
type:
- string
- 'null'
keeps_processes:
type: boolean
previews_resume_on_wake:
type: boolean
keep_awake_until:
type:
- string
- 'null'
yours:
type: boolean
owner:
type:
- string
- 'null'
access:
type: string
enum:
- personal
- team
- machine
is_origin_device:
type: boolean
roots:
type: array
items:
type: object
properties:
id:
type: string
label:
type:
- string
- 'null'
repository:
type:
- string
- 'null'
direct_operations:
type: array
items:
type: string
enum:
- fs.read
- fs.write
- fs.export
- fs.import
- exec.run
- exec.full
- process.run.v1
- process.full.v1
- computer.use
- browser.use
- simulator.call.v1
process_limits:
type: object
propertyNames:
type: string
enum:
- process.run.v1
- process.full.v1
additionalProperties:
type: object
properties:
default_timeout_ms:
type: number
const: 600000
max_timeout_ms:
type: integer
minimum: 1000
maximum: 1800000
required:
- default_timeout_ms
- max_timeout_ms
additionalProperties: false
browser_recording:
type: object
properties:
available:
type: boolean
version:
type: number
const: 1
proof_ready:
type: boolean
const: false
pr_proof_guidance:
type: string
const: >-
browser_recording is ordinary capture only; its
proof_ready=false does not describe PR proof
support. Check browser_pr_proof. For video, first
use tools.pr.checkVideoAuth with an advertised
browser_profile; use tools.pr.prepareProof for the
advertised evidence format. Inventory does not
establish authentication or verified evidence.
required:
- available
- version
- proof_ready
additionalProperties: false
browser_pr_proof:
type: object
properties:
available:
type: boolean
version:
anyOf:
- anyOf:
- type: number
const: 2
- type: number
const: 3
- type: 'null'
image:
type: boolean
video:
type: boolean
profiles:
maxItems: 16
type: array
items:
type: string
pattern: ^(Default|Profile [0-9]+)$
required:
- available
- version
- image
- video
- profiles
additionalProperties: false
permissions:
type: object
properties:
read:
type: boolean
write:
type: boolean
execute:
type: boolean
discover_environment:
type: boolean
expose_mcp:
type: boolean
required:
- read
- write
- execute
- discover_environment
- expose_mcp
additionalProperties: false
required:
- id
- label
- repository
- permissions
additionalProperties: false
versions:
type: object
properties:
latest_cli_versions:
type: object
properties:
production:
type: string
staging:
type: string
additionalProperties: false
worker:
type: object
properties:
running_version:
type:
- string
- 'null'
installed_version:
type:
- string
- 'null'
channel:
type:
- string
- 'null'
observed_at:
type:
- string
- 'null'
latest_published_version:
type:
- string
- 'null'
comparison:
type: string
enum:
- unknown
- current
- older
- newer
required:
- running_version
- installed_version
- channel
- observed_at
- latest_published_version
- comparison
additionalProperties: false
desktop:
type:
- object
- 'null'
properties:
running_version:
type:
- string
- 'null'
installed_version:
type:
- string
- 'null'
channel:
type:
- string
- 'null'
observed_at:
type:
- string
- 'null'
latest_published_version:
type:
- string
- 'null'
comparison:
type: string
enum:
- unknown
- current
- older
- newer
architecture:
oneOf:
- type: string
enum:
- arm64
- x64
- type: 'null'
commit:
type:
- string
- 'null'
started_at:
type:
- string
- 'null'
required:
- running_version
- installed_version
- channel
- observed_at
- latest_published_version
- comparison
- architecture
- commit
- started_at
additionalProperties: false
required:
- latest_cli_versions
- worker
- desktop
additionalProperties: false
desktop_available:
type: boolean
screen_lock:
type: string
enum:
- locked
- unlocked
- unknown
required:
- id
- name
- kind
- reason_id
- size
- os
- state
- live
- unavailable_reason
- this_session
- sessions
- rcu_per_hour
- keeps_processes
- previews_resume_on_wake
- keep_awake_until
additionalProperties: false
cloud_sizes:
type: array
items:
type: object
properties:
size:
type: string
enum:
- s
- m
- l
- xl
memory_mb:
type: number
vcpus:
type:
- number
- 'null'
rcu_per_hour:
type:
- string
- 'null'
required:
- size
- memory_mb
- vcpus
- rcu_per_hour
additionalProperties: false
default_cloud_size:
type: string
enum:
- s
- m
- l
- xl
view_only_count:
type: integer
minimum: 0
desktop_origin:
type: object
properties:
status:
type: string
enum:
- missing
- unavailable
- unauthorized
- available
device_id:
type:
- string
- 'null'
unavailable_reason:
type:
- string
- 'null'
required:
- status
- device_id
- unavailable_reason
additionalProperties: false
machine_selection:
type:
- object
- 'null'
properties:
source:
type: string
const: user
target:
oneOf:
- type: object
properties:
kind:
type: string
const: cloud
required:
- kind
additionalProperties: false
- type: object
properties:
kind:
type: string
const: machine
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)$
name:
type: string
minLength: 1
maxLength: 63
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)$
cwd:
type: string
maxLength: 4096
isolation:
type: string
enum:
- worktree
- in_place
required:
- kind
- device_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)$
cwd:
type: string
maxLength: 4096
isolation:
type: string
enum:
- worktree
- in_place
workspace_mode:
type: string
enum:
- managed
- project_root
workspace_path:
type: string
maxLength: 4096
required:
- kind
- device_id
additionalProperties: false
required:
- source
- target
additionalProperties: false
required:
- computers
- cloud_sizes
- default_cloud_size
additionalProperties: false
description: >-
Computers visible to the caller, with available cloud sizes. kind is
cloud, mac, cli or worker. A cloud computer's state is ready whether
awake or parked: live=true means awake, live=false means parked or not
yet booted; busy means resizing. For connected computers, state=ready
means available and state=offline means unavailable; live is always
false. reason_id identifies a cloud computer's Reason; size is null for
connected computers. Connected computers may include owner and yours.
Session titles are included only for the caller's own Sessions. Listing
never grants execution access or wakes a computer.
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.
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
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: session_not_found
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
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, devices:read, devices:write, devices:use,
computers:read, computers:write, ssh:write, 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. devices:write, devices:use,
computers:read, computers:write, ssh:write, network:read and
network:write are opt-in, excluded from default keys. computers:read
lists visible cloud and connected computers without waking them or
granting execution access. devices:read discovers local Device targets;
devices:use separately consents to local execution, so a
discover-and-run local workflow needs both. devices:write manages
enrollment and device grants; computers:write creates or deletes cloud
computers; ssh:write manages retained SSH access. 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.