---
title: "List Reasons"
method: GET
path: "/v3/organizations/{orgId}/reasons"
tags: ["Reasons"]
---

# List Reasons

`GET /v3/organizations/{orgId}/reasons`

## Request

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

A Reason is the long-running agent a person keeps: their main Reason, plus named ones for areas of work. Each Reason has its own conversation, its own Loops (scheduled and triggered work) and the Sessions it starts, which are filed under it. Messaging a Reason (sendReasonMessage) is the primary way to give it work.

Lists the caller's own Reasons first (main, then named ones oldest first), then other members' Reasons shared with the workspace or with the caller. Another member's Reason is listed without its conversation `session_id` and instructions.

<sub>Scope: `sessions:read`</sub>

## Response `200`

The Reasons the caller can see.

- ReasonList
  - `items` Reason[], required: The caller's own Reasons (main first, then named ones oldest first), then other members' workspace-visible Reasons.
    - `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

- `401`: Missing, invalid, or expired key.
- `403`: The key lacks the required scope or role.
- `429`: Too many requests. Retry after the number of seconds in the `Retry-After` response header.

## Changes

- **2026-10-26** `c250866428e0`: 4 info
  - added the required property `items/items/audience` to the response with the `200` status
  - added the required property `items/items/default_model` to the response with the `200` status
  - added the required property `items/items/default_reasoning_effort` to the response with the `200` status
  - added the required property `items/items/default_repositories` to the response with the `200` status
- **2026-10-17** `f7495fe90970`: 1 info
  - added the required property `items/items/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/get.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)