> ## 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 workspace computers
> Lists cloud and connected computers visible to the caller in this workspace, using the same personal visibility and sharing rules as Reason's computer inventory. Requires the explicitly granted computers:read scope, which is excluded from default keys. Includes eligible Reasons' cloud computers, the caller's running cloud computers outside a Reason, and eligible connected computers; administrator-only viewable devices are not exposed. Cloud live distinguishes awake from parked; connected state describes availability. This read does not wake machines or grant execution authority. For local execution, devices:read discovers Device targets and devices:use separately authorizes execution on an eligible target.
Scope: `computers:read`
## OpenAPI
````yaml /openapi.json get /v3/organizations/{orgId}/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}/computers:
parameters:
- $ref: '#/components/parameters/orgId'
get:
tags:
- Computers
summary: List workspace computers
description: >-
Lists cloud and connected computers visible to the caller in this
workspace, using the same personal visibility and sharing rules as
Reason's computer inventory. Requires the explicitly granted
computers:read scope, which is excluded from default keys. Includes
eligible Reasons' cloud computers, the caller's running cloud computers
outside a Reason, and eligible connected computers; administrator-only
viewable devices are not exposed. Cloud live distinguishes awake from
parked; connected state describes availability. This read does not wake
machines or grant execution authority. For local execution, devices:read
discovers Device targets and devices:use separately authorizes execution
on an eligible target.
Scope: `computers:read`
operationId: listComputers
responses:
'200':
description: The caller's computer inventory.
content:
application/json:
schema:
$ref: '#/components/schemas/ComputersList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'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
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.