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

# API overview

> Base URL, authentication, defaults, polling, and errors for the Reason HTTP API. Every endpoint is listed in the reference.

The Reason HTTP API creates and continues Sessions, reads their events, and manages the computers, secrets, skills and automations they use. Every endpoint is in the reference on the left.

## Base URL

```text theme={null}
https://api.reasonmachines.com/v3
```

Organization-scoped paths start with `/v3/organizations/{orgId}`. Get `orgId` once from `GET /v3/self`, which returns `org_id`.

## Authentication

Send an API key as a bearer token:

```bash theme={null}
curl -fsS -H "Authorization: Bearer $REASON_API_KEY" https://api.reasonmachines.com/v3/self
```

A key carries scopes, and each endpoint names the scope it needs. Read [Authentication and scopes](https://ara-90a60a07.mintlify.site/docs/build/auth-and-scopes.md) for the full table and the other sign-in methods.

## Start with these calls

| Step | Endpoint |
| - | - |
| Confirm the key and get the organization | `GET /v3/self` |
| Create a Session | `POST /v3/organizations/{orgId}/sessions` |
| Read its status and events | `GET /v3/organizations/{orgId}/sessions/{sessionId}/events` |
| Send a follow-up | `POST /v3/organizations/{orgId}/sessions/{sessionId}/messages` |
| Cancel it | `POST /v3/organizations/{orgId}/sessions/{sessionId}/cancel` |
| List your computers | `GET /v3/organizations/{orgId}/devices` |

## Defaults

* A Session created without `target` runs in Reason's cloud. Name a `target` to run on your computer.
* Session lists return newest first and exclude archived Sessions unless you pass `status=archived` or `status=all`.
* Work starts asynchronously. Creating a Session returns at once with its ID, so poll for its state.
* A Session's `outcome` is the task result. `status` only says whether execution finished: a Session can end with `status: exit` and `outcome: failure`.

## Polling, not streaming

Events are read by polling `GET .../events` with `after_seq` and `wait_ms`. Each call returns the events after your cursor, and with `wait_ms` it waits for the next one. Read [Events reference](https://ara-90a60a07.mintlify.site/docs/build/events-reference.md) for the cursor, duplicates and ordering.

## Errors

Errors return a JSON body with an `error` object that has a `type` and a `message`. The status code tells you what to do:

| Status | Meaning | What to do |
| - | - | - |
| `400` | The body is invalid, or a host or field is rejected | Fix the request; do not retry as is |
| `401` | The key is missing, expired or wrong | Check the key in **Settings > API** |
| `403` | The key lacks a scope, or your role is too low | Read `missing_scope` in the body, then grant that scope |
| `404` | The resource does not exist or you cannot see it | Check the ID |
| `409` | The request conflicts with current state | Read the reason in the body and retry after it changes |
| `429` | The key is rate-limited | Back off and retry later |

Read the body before you retry. Do not widen a key's scopes to get past an error that names a missing one.

## Versions

This reference is version 3 of the API (`info.version` is `3.0.0`). Deprecated operations say so in their description, and point to their replacement.


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