> ## 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.
# Get a Reason
> Returns one Reason the caller can see: their own, or another member's Reason shared with the workspace or with them. Any other id, an archived Reason included, returns 404 `reason_not_found`.
Scope: `sessions:read`
## OpenAPI
````yaml /openapi.json get /v3/organizations/{orgId}/reasons/{reasonId}
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}:
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:
- Reasons
summary: Get a Reason
description: >-
Returns one Reason the caller can see: their own, or another member's
Reason shared with the workspace or with them. Any other id, an archived
Reason included, returns 404 `reason_not_found`.
Scope: `sessions:read`
operationId: getReason
responses:
'200':
description: The Reason.
content:
application/json:
schema:
$ref: '#/components/schemas/Reason'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
security:
- reasonApiKey:
- sessions: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:
Reason:
type: object
properties:
id:
type: string
format: uuid
description: Reason id. Pass it as `reasonId` to the other Reason tools.
name:
type: string
description: Display name. The main Reason is always called Reason.
user_id:
type: string
format: uuid
description: The owner, the only person who can open, rename or archive it.
mine:
type: boolean
description: True when the caller owns this Reason.
visibility:
type: string
enum:
- workspace
- private
description: >-
`workspace`: every member sees it in their list; `private`: only its
owner does.
main:
type: boolean
description: >-
True for the person's main Reason, which is always listed and is
never renamed or archived.
appearance:
$ref: '#/components/schemas/ReasonAppearance'
instructions:
type: string
description: >-
Plain-text guidance for new Sessions started with this Reason. Blank
when unset or when the caller does not own the Reason.
session_id:
description: >-
Its conversation Session once it has been opened, and only on the
caller's own Reasons; null otherwise. sendReasonMessage and
listReasonMessages reach the conversation of any Reason you can open
without it.
type:
- string
- 'null'
default_model:
description: >-
The model a new Session under this Reason starts on when its create
names none, by an id listAgentModels returns; null when it uses the
workspace's default.
type:
- string
- 'null'
default_reasoning_effort:
description: >-
The reasoning effort that Session starts at when its create names
none; null for the model's default.
oneOf:
- type: string
enum:
- minimal
- low
- medium
- high
- xhigh
- max
- 'off'
- type: 'null'
default_repositories:
description: >-
The `owner/name` repositories a new Session under this Reason checks
out when its create names none, the first being the Session's own;
empty when it has none. Null when the caller cannot start Sessions
under this Reason.
type:
- array
- 'null'
items:
type: string
audience:
type: string
enum:
- personal
- team
- customer
description: >-
Who talks to it. `personal`: only its owner; `team`: the people it
is shared with; `customer`: a team Reason that people outside the
team (customers, in Slack for example) also talk to, whose runs use
only what was added to the Reason itself.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- name
- user_id
- mine
- visibility
- main
- appearance
- instructions
- session_id
- default_model
- default_reasoning_effort
- default_repositories
- audience
- created_at
- updated_at
description: >-
A Reason is the long-running agent a person keeps: their main Reason, or
a named one for an area of work. Each has its own conversation, its own
Loops (scheduled and triggered work) and the Sessions it starts, which
are filed under it. Messaging the Reason is the primary way to give it
work: it decides whether to answer, start Sessions or set up Loops.
ReasonAppearance:
type: object
properties:
color:
type: string
enum:
- black
- blue
- orange
- green
- purple
- red
- teal
- pink
- amber
- brown
- grey
- white
description: >-
Body colour of the Reason's bot avatar in the app, which tells
Reasons apart at a glance.
eyes:
type: string
enum:
- pills
- dots
- small
- wide
- sleepy
- brows
description: Eye style of the Reason's bot avatar in the app.
glasses:
type: string
enum:
- none
- round
- square_shades
- aviators
- round_shades
- monocle
- magnifier
description: Glasses the Reason's bot avatar wears; `none` leaves it without.
accessory:
type: string
enum:
- none
- headphones
- bow_tie
- beret
- bowler
- cap
- antenna
- crown
- party_hat
- top_hat
description: >-
Hat or accessory the Reason's bot avatar wears; `none` leaves it
bare.
required:
- color
- eyes
- glasses
- accessory
description: >-
How the Reason's bot avatar looks in the app. Purely visual; it changes
nothing the agent does.
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, 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.