> ## 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.

# Reasons

> A Reason is the long-running agent you keep, with its own instructions, model, repositories, Loops and Sessions. Create, share, message and delete Reasons.

A Reason is the long-running agent you keep. You have a main Reason, and you can add named ones for areas of work, such as release notes or support. Each Reason has its own:

* **Instructions**: plain-text guidance every new Session started with the Reason receives.
* **Conversation**: one long-running chat where you give it work.
* **Sessions**: the tasks it starts, which are filed under it.
* **[Loops](https://ara-90a60a07.mintlify.site/docs/loops.md)**: its scheduled and event-driven work.
* **Defaults**: the model, reasoning effort and repositories its new Sessions start with.

## Your main Reason and named Reasons

Every person has exactly one main Reason in a Workspace. It is listed first, is never deleted, and holds the Sessions and Loops you have not filed under another Reason. Your main Reason stays personal: its Sessions are yours alone, and Workspace owners and admins do not get them either.

Named Reasons are the ones you create. You can make one of your own named Reasons your main one, as long as it is personal and has never been shared. It keeps its name, instructions, memory and Sessions, and the former main Reason becomes an ordinary named Reason. In the app, your main Reason's menu has **Replace with different Reason**.

## Give a Reason work

Messaging a Reason is the main way to give it work. Your message goes into its conversation, and the Reason decides how to do the work: it answers, starts Sessions, or sets up Loops.

A message sent while the Reason is working steers its running turn. Anyone the Reason is shared with may message it, and each turn acts as the person who sent the message.

From a terminal:

```bash theme={null}
reason reasons                                              # the Reasons you can give work to
reason reasons ask main "Summarize yesterday's failed CI runs"
reason reasons ask "Release notes" "Draft the notes for this week" --detach
```

`NAME` is a Reason's name in any case, its id, or `main`. `--queue` waits for its running turn to end first, `--detach` returns once the message is accepted, and `--json` prints machine-readable output. `reason agents` is the same command.

## Create and set up a Reason

In the app, choose **New Reason** in the sidebar. The Reason opens on its empty conversation; tell it what it is for.

To change a Reason, ask it in its own chat, for example "Rename yourself to Release notes" or "From now on, keep answers short". The API changes the same settings. What you can set:

| Setting | What it does |
| - | - |
| Name | What the Reason is listed under, up to 80 characters |
| Avatar | The colour and eyes of its bot avatar. Purely visual |
| Instructions | Up to 16,000 characters of plain text that every new Session started with the Reason receives |
| Default model and reasoning effort | What new Sessions under it start on when they name none. Without one, they use the Workspace's default |
| Default repositories | Up to 6 connected repositories new Sessions check out. The first is the Session's own; the rest are context |
| Sharing | Whether everyone in the Workspace has it |

A change applies from then on. Sessions that are already running keep what they started with.

### Default model

A Reason's default model is what its new Sessions start on when they pick none.

In the app, open the Reason, choose **Details**, and set **Default model** under Instructions. Its owner and managers can change it; asking the Reason to change its model does the same.

* **Workspace default** follows the Workspace's default model in **Settings › Models**, and changes when that does. A Reason starts here.
* **A fixed model** is one of Reason's models or a connected account's model, with its reasoning effort. The list shows which account each model runs on.

A new Session uses, in order, the model picked for that Session, the Reason's default, then the Workspace's default. This covers Sessions you start in the app, the Sessions the Reason or another Session starts, its Loops and its Slack conversations. Sessions that have already started keep their model.

* If the fixed model's account is disconnected, or no longer has the model, new Sessions start on another model the Workspace can run, when there is one, beginning with its Model priority list. The row says so until you reconnect the account or pick another model.
* A Session that runs on a connected account keeps that account's model for the Sessions it starts, unless the Reason's default is another connected account's model. Work on your subscription does not move to Reason credits.
* A Session created with the REST API names its own model or uses the Workspace's default.

The row appears once the Workspace has connected a model account of its own. Without one, every Session runs on Reason's model for the plan.

A named Reason can also have a start step and an end step that every Session under it carries out. They are in preview: see [Start and end steps](https://ara-90a60a07.mintlify.site/docs/workspaces.md#start-and-end-steps).

## Share a Reason

* In a Workspace with two or more people, a new Reason starts shared with everyone. In a Workspace of one it starts private.
* **Share this Reason** on a Reason sets who has it: everyone in the Workspace, people you invite, or only you.
* Sharing has two levels. A **Collaborator** can chat with the Reason. A **Manager** can also edit its settings and share it with others.
* Everyone a Reason is shared with can talk to it, start Sessions under it, and read and continue its Sessions and Loops. Each person's own chat with a team Reason stays theirs.
* Sharing a Reason makes it a team Reason: its Sessions run in the cloud and never use anyone's personal secrets.
* Your main Reason cannot be shared. To share work from it, use **Share** on a Session, which makes a new shared Reason.

See [Workspaces and sharing](https://ara-90a60a07.mintlify.site/docs/workspaces.md) for what a Workspace shares with every Reason in it.

## Delete a Reason

Only a Reason's owner deletes it, and the main Reason is never deleted. Deleting a named Reason:

* Removes it from every Reason list.
* Deletes its Loops, so nothing scheduled or triggered runs for it.
* Removes its own Slack app, if it has one.
* Archives its conversation with its history.

The Sessions it started stay where they are. Nothing restores a deleted Reason.

The API's [Archive a Reason](https://ara-90a60a07.mintlify.site/api-reference/reasons/archive-a-reason.md) is the same operation as delete, under its older name.

## Limits

* A Workspace holds at most 500 live named Reasons. Main Reasons do not count.
* A name is at most 80 characters and instructions at most 16,000.
* A Reason has at most 6 default repositories.

## API

Every call needs an API key with the scope shown. See [Authentication and scopes](https://ara-90a60a07.mintlify.site/docs/build/auth-and-scopes.md).

| Do | Call | Scope |
| - | - | - |
| List Reasons | [`GET /v3/organizations/{orgId}/reasons`](https://ara-90a60a07.mintlify.site/api-reference/reasons/list-reasons) | `sessions:read` |
| Read one | [`GET .../reasons/{reasonId}`](https://ara-90a60a07.mintlify.site/api-reference/reasons/get-a-reason) | `sessions:read` |
| Create one | [`POST .../reasons`](https://ara-90a60a07.mintlify.site/api-reference/reasons/create-a-reason) | `run` |
| Change one | [`PATCH .../reasons/{reasonId}`](https://ara-90a60a07.mintlify.site/api-reference/reasons/update-a-reason) | `run` |
| Message one | [`POST .../reasons/{reasonId}/messages`](https://ara-90a60a07.mintlify.site/api-reference/reasons/message-a-reason) | `run` |
| Read its conversation | [`GET .../reasons/{reasonId}/messages`](https://ara-90a60a07.mintlify.site/api-reference/reasons/list-a-reasons-messages) | `sessions:read` |
| Make it your main Reason | [`POST .../reasons/{reasonId}/make-main`](https://ara-90a60a07.mintlify.site/api-reference/reasons/make-a-reason-the-main-one) | `run` |
| Delete one | [`DELETE .../reasons/{reasonId}`](https://ara-90a60a07.mintlify.site/api-reference/reasons/delete-a-reason) | `run` |

Creating a Reason allocates no computer and starts no work. Send it a message to start:

```bash theme={null}
curl -sS -X POST "https://api.reasonmachines.com/v3/organizations/$ORG_ID/reasons" \
  -H "Authorization: Bearer $REASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Release notes", "instructions": "Write release notes in plain language." }'

curl -sS -X POST "https://api.reasonmachines.com/v3/organizations/$ORG_ID/reasons/$REASON_ID/messages" \
  -H "Authorization: Bearer $REASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Draft the notes for this week." }'
```

The message call returns once the message is accepted, not when the Reason answers. Poll the Reason's messages with the last `end_cursor` for its reply.

The Reason's owner and its managers change its setup. Anyone else it is shared with gets `403 reason_manager_required`.

## Next steps

* [Loops](https://ara-90a60a07.mintlify.site/docs/loops.md): standing work a Reason does on a schedule or an event.
* [Memory](https://ara-90a60a07.mintlify.site/docs/memory.md) and [Skills](https://ara-90a60a07.mintlify.site/docs/skills.md): what Reasons know and how they work.
* [Slack](https://ara-90a60a07.mintlify.site/docs/slack.md): talk to a Reason from Slack.
* [GitHub](https://ara-90a60a07.mintlify.site/docs/github.md): the repositories a Reason works in, and its pull requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.