> ## 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.
# Update a Reason
> Changes a Reason's name, avatar, or both. Only the owner can update a Reason; any other id returns 404.
Scope: `run`
## OpenAPI
````yaml /openapi.json patch /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: Devices
description: >-
Owned Mac and headless Device identity, bounded enrollment and root
grants.
- 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: Account
description: Verify a key and resolve the organization it belongs to.
- name: Feedback
description: Report problems with the API or these docs to the Reason team.
- name: Projects
description: >-
Retired in favour of Reasons. Existing workspace projects remain readable
over REST.
- name: Reasons
description: >-
A person's long-running agent conversations: their main Reason and named
ones. Message a Reason by opening its conversation and sending to that
Session.
- 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: 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: Secrets
description: >-
Encrypted credentials injected into the agent's sandbox. Write-only:
values can be set but never read back.
- name: Knowledge
description: >-
Retired. Workspace notes and knowledge folders have been removed; every
operation returns 410.
- 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}/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
patch:
tags:
- Reasons
summary: Update a Reason
description: >-
Changes a Reason's name, avatar, or both. Only the owner can update a
Reason; any other id returns 404.
Scope: `run`
operationId: updateReason
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateReason'
responses:
'200':
description: The updated Reason.
content:
application/json:
schema:
$ref: '#/components/schemas/Reason'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: The main Reason cannot be renamed (`main_reason_name_fixed`).
'429':
$ref: '#/components/responses/RateLimited'
security:
- reasonApiKey:
- 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:
UpdateReason:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 80
description: >-
The name to list the Reason under from now on; its conversation
Session is retitled to match. The main Reason keeps its name (409).
appearance:
$ref: '#/components/schemas/ReasonAppearance'
description: >-
Send `name`, `appearance` or both; fields left out keep their value. A
new `appearance` on the main Reason changes the person's Reason avatar.
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'
session_id:
description: >-
Its conversation Session once it has been opened, and only on the
caller's own Reasons; null otherwise. Use it with sendSessionMessage
and listSessionConversation.
type:
- string
- 'null'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- name
- user_id
- mine
- visibility
- main
- appearance
- session_id
- created_at
- updated_at
description: >-
A long-running agent conversation the person keeps: their main Reason or
a named one. Sessions it starts are filed under it.
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:
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: 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. 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.