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

# Introduction

> Reason Machines documentation — cloud software-engineering agents, the HTTP API, and Reason MCP.

# Reason Machines

Reason is an autonomous software engineer for GitHub. Connect a repository, assign work, and Reason's cloud agents open evidence-backed pull requests — with screen recordings, logs, and review-ready diffs.

People drive Reason from the web app at [reasonmachines.com](https://reasonmachines.com). Programmatic access uses the HTTP API and Reason MCP documented here.

## Start here

<CardGroup cols={2}>
  <Card title="Verify credentials" icon="key" href="/api-reference/account/verify-credentials">
    Confirm your API key, scopes, and organization with `GET /v3/self`.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/account/verify-credentials">
    Full OpenAPI reference for sessions, projects, secrets, skills, and more.
  </Card>
</CardGroup>

## HTTP API

* **Base URL:** `https://api.reasonmachines.com`
* **Auth:** `Authorization: Bearer <api_key>`
* Mint a key from Reason Settings → API. New keys use `reason_` followed by 64 hexadecimal characters; legacy `ara_` keys remain accepted.
* Resolve your workspace with `GET /v3/self`, then call `/v3/organizations/:orgId/*`.
* Health: `GET https://api.reasonmachines.com/healthz`

## Reason MCP

* **URL:** `https://mcp.reasonmachines.com/mcp` (Streamable HTTP)
* Sign in through your MCP client's OAuth browser flow and choose a workspace.
* Example (Claude Code): `claude mcp add --transport http reason https://mcp.reasonmachines.com/mcp`, then `/mcp` to authenticate.
* Publisher plugins and other clients: [https://github.com/reason-machines/ara-mcp](https://github.com/reason-machines/ara-mcp)
* Start with `getSelf`, `listProjects`, or `listSessions`.

The legacy public MCP at `/mcp/ara` remains retired. Prefer Reason MCP or the `/v3` HTTP API with a Reason API key.

## Create a session

```bash theme={null}
curl -sS https://api.reasonmachines.com/v3/organizations/$ORG_ID/sessions \
  -H "Authorization: Bearer $REASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fix the flaky auth test, add a regression case, and open a PR.",
    "repo": "acme/web",
    "provider": "github",
    "idempotency_key": "one-stable-key-per-logical-run"
  }'
```

Poll `GET /v3/organizations/:orgId/sessions/:sessionId`. Status is `running`, `exit` (success), `error`, or `suspended`. Only `exit` means the run completed successfully.

For agent-oriented discovery, see [llms.txt](/llms.txt).