---
title: "Update a Reason"
method: PATCH
path: "/v3/organizations/{orgId}/reasons/{reasonId}"
tags: ["Reasons"]
---

# Update a Reason

`PATCH /v3/organizations/{orgId}/reasons/{reasonId}`

## Request

- Base URL: `https://api.reasonmachines.com`
- URL: `https://api.reasonmachines.com/v3/organizations/{orgId}/reasons/{reasonId}`
- Auth: HTTP bearer

Changes how a Reason works from now on: its name, avatar and plain-text instructions; the model, reasoning effort and repositories new Sessions under it start with when their create names none; whether everyone in the workspace has it (`visibility`); and whether people outside the team may talk to it (`audience`). Sessions already running are unchanged. Fields left out keep their value.

The Reason's owner and the people it is shared with as managers (a role set in the Reason app) make these changes; anyone else it is shared with gets 403 `reason_manager_required`, and an id the caller cannot see returns 404. The main Reason is always called Reason (409 `main_reason_name_fixed`) and stays personal (409 `main_reason_personal` or `main_reason`).

<sub>Scope: `run`</sub>

## Request body

- UpdateReason: Send any of the fields; fields left out keep their value. A new `appearance` on the main Reason changes the person's Reason avatar. The fields are written one after another, so a refusal (for example 409 on `audience`, which is applied last) leaves the fields before it written.
  - `instructions` string: Plain-text guidance for new Sessions started with this Reason. At most 16000 UTF-16 code units to protect fixed Session context. Preserved exactly, including whitespace. Send an empty string to clear it; omitting it keeps the current value on update. Existing Sessions are unchanged.
  - `name` string: 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` ReasonAppearance: How the Reason's bot avatar looks in the app. Purely visual; it changes nothing the agent does.
    - `color` 'black' | 'blue' | 'orange' | 'green' | 'purple' | 'red' | 'teal' | 'pink' | 'amber' | 'brown' | 'grey' | 'white', required: Body colour of the Reason's bot avatar in the app, which tells Reasons apart at a glance.
    - `eyes` 'pills' | 'dots' | 'small' | 'wide' | 'sleepy' | 'brows', required: Eye style of the Reason's bot avatar in the app.
    - `glasses` 'none' | 'round' | 'square_shades' | 'aviators' | 'round_shades' | 'monocle' | 'magnifier', required: Glasses the Reason's bot avatar wears; `none` leaves it without.
    - `accessory` 'none' | 'headphones' | 'bow_tie' | 'beret' | 'bowler' | 'cap' | 'antenna' | 'crown' | 'party_hat' | 'top_hat', required: Hat or accessory the Reason's bot avatar wears; `none` leaves it bare.
  - `default_model` string, nullable: The model new Sessions under this Reason start on when their create names none, by an id listAgentModels returns, or null to use the workspace's default again. Sessions already running keep their model. An id this workspace cannot choose is refused with 400 `invalid_model`.
  - `default_reasoning_effort` 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'off', nullable: The reasoning effort those Sessions start at, or null for the model's default. Sent only together with `default_model`.
  - `default_repositories` string[]: The connected `owner/name` repositories new Sessions under this Reason check out when their create names none: up to 6, unique, the first being the Session's own and the rest its context. Send an empty list to clear them.
  - `visibility` 'workspace' | 'private': `workspace` shares the Reason with everyone in the workspace, who can then talk to it and start Sessions under it; `private` stops that (people it is shared with by name keep it). Sharing a Reason makes it a team Reason: its Sessions run in the cloud and never use anyone's personal secrets.
  - `audience` 'customer' | 'default': `customer` lets people outside your team talk to a team Reason (a shared, named Reason; 409 `reason_not_team` otherwise, 409 `main_reason` for the main one): from then on its runs use only what was added to the Reason itself. `default` makes it a plain team or personal Reason again, as its sharing says. Applied after every other field.

## Response `200`

The updated Reason.

- Reason: 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.
  - `id` string, uuid, required: Reason id. Pass it as `reasonId` to the other Reason tools.
  - `name` string, required: Display name. The main Reason is always called Reason.
  - `user_id` string, uuid, required: The owner, the only person who can open, rename or archive it.
  - `mine` boolean, required: True when the caller owns this Reason.
  - `visibility` 'workspace' | 'private', required: `workspace`: every member sees it in their list; `private`: only its owner does.
  - `main` boolean, required: True for the person's main Reason, which is always listed and is never renamed or archived.
  - `appearance` ReasonAppearance, required: How the Reason's bot avatar looks in the app. Purely visual; it changes nothing the agent does.
    - `color` 'black' | 'blue' | 'orange' | 'green' | 'purple' | 'red' | 'teal' | 'pink' | 'amber' | 'brown' | 'grey' | 'white', required: Body colour of the Reason's bot avatar in the app, which tells Reasons apart at a glance.
    - `eyes` 'pills' | 'dots' | 'small' | 'wide' | 'sleepy' | 'brows', required: Eye style of the Reason's bot avatar in the app.
    - `glasses` 'none' | 'round' | 'square_shades' | 'aviators' | 'round_shades' | 'monocle' | 'magnifier', required: Glasses the Reason's bot avatar wears; `none` leaves it without.
    - `accessory` 'none' | 'headphones' | 'bow_tie' | 'beret' | 'bowler' | 'cap' | 'antenna' | 'crown' | 'party_hat' | 'top_hat', required: Hat or accessory the Reason's bot avatar wears; `none` leaves it bare.
  - `instructions` string, required: Plain-text guidance for new Sessions started with this Reason. Blank when unset or when the caller does not own the Reason.
  - `session_id` string, nullable, required: 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.
  - `default_model` string, nullable, required: 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.
  - `default_reasoning_effort` 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'off', nullable, required: The reasoning effort that Session starts at when its create names none; null for the model's default.
  - `default_repositories` string[], nullable, required: 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.
  - `audience` 'personal' | 'team' | 'customer', required: 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` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Invalid request.
- `401`: Missing, invalid, or expired key.
- `403`: The key lacks the required scope or role.
- `404`: Resource not found.
- `409`: The main Reason cannot be renamed (`main_reason_name_fixed`), shared (`main_reason_personal`) or opened to people outside the team (`main_reason`), or `audience` customer was sent for a Reason that is not shared with the team (`reason_not_team`).
- `429`: Too many requests. Retry after the number of seconds in the `Retry-After` response header.

## Changes

- **2026-10-26** `c250866428e0`: 1 breaking, 9 info
  - added the pattern `^[^\u0000]*$` to the request property `name`
  - added the new optional request property `audience`
  - added the new optional request property `default_model`
  - added the new optional request property `default_reasoning_effort`
  - …6 more
- **2026-10-17** `f7495fe90970`: 2 info
  - added the new optional request property `instructions`
  - added the required property `instructions` to the response with the `200` status
- **2026-10-15** `fad7b15a74a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ara/apis/reason-api/changes/v3/organizations/:orgId/reasons/:reasonId/patch.md)

---

[API](https://skmtc.dev/ara/apis/reason-api.md) - [All operations](https://skmtc.dev/ara/apis/reason-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ara/apis/reason-api/revisions/e97c8704807c?raw)