# Reason

OpenAPI JSON: https://api.reasonmachines.com/v3/openapi.json

> Reason is an autonomous software engineer for GitHub. Connect a repository, assign
> issues, 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
> https://reasonmachines.com; programmatic per-user access is available through the HTTP API.

## Public product and pricing information

Read the public website without authentication. HTML is the default for browsers
and crawlers; Markdown copies are available through the links below or an explicit
`Accept: text/markdown` request.

- Product overview: https://reasonmachines.com/product
- Current pricing, RCU plans, machine rates, and billing terms: https://reasonmachines.com/pricing
- Pricing Markdown: https://reasonmachines.com/pricing.md
- Complete public content: https://reasonmachines.com/llms-full.txt
- Canonical page inventory: https://reasonmachines.com/sitemap.xml

To operate a user's account or start work, use the authenticated HTTP API or
Reason MCP described below. Do not connect to `/mcp/ara`; that old public
transport remains retired.

## HTTP API

- Base URL: `https://api.reasonmachines.com`
- Auth: `Authorization: Bearer <api_key>`
- Mint a key from Reason Settings → API. A new key includes the ordinary
  public scopes for this walkthrough.
- New keys use `reason_` followed by 64 hexadecimal characters.
  Legacy `ara_` keys remain accepted.
- Credential check: `GET /v3/self`
- Workspace scope: use `/v3/organizations/:orgId/*`, where `:orgId` can be the
  workspace id or slug.
- Health: `GET https://api.reasonmachines.com/healthz`
- All responses are JSON.
- Rate limiting: any authenticated request may return HTTP 429 with an
  `error.type` of `rate_limited` and a `Retry-After` header in seconds. Wait that
  long before retrying the same request.
- Credential reference: https://docs.reasonmachines.com/api-reference/account/verify-credentials
- Full endpoint reference: https://docs.reasonmachines.com/api-reference
- Report a wrong, surprising, or blocking API behavior: `POST /v3/feedback`
  with `category` and `note` (any valid key; never include secrets).
- Legacy public MCP (`GET`/`POST` `/mcp/ara`) returns 410. Use the new MCP below
  or `/v3` with a Reason API key.

## Reason MCP

- URL: `https://mcp.reasonmachines.com/mcp` (Streamable HTTP)
- Sign in through your MCP client's OAuth browser flow and choose a workspace.
- Claude Code: `claude mcp add --transport http reason https://mcp.reasonmachines.com/mcp`, then /mcp to authenticate.
- Codex: `codex mcp add reason --url https://mcp.reasonmachines.com/mcp`, then `codex mcp login reason`.
- Publisher-owned Claude and Codex plugins: https://github.com/reason-machines/ara-mcp
- Tools follow active v3 operation IDs and the same scope and workspace checks.
  Path/query arguments are top-level; request bodies go in `body`.
- Start with `getSelf`, `listProjects`, or `listSessions`. Follow pagination.
- OAuth audiences are separate: REST grants cannot be reused at MCP.
- Downloads return authorized links. Base64 uploads are capped at 1 MiB; use REST
  for larger files. Results are capped at 2 MiB; request smaller pages if needed.

## Start and monitor a session

Create a session with `POST /v3/organizations/:orgId/sessions`:

```json
{
  "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"
}
```

- `prompt` is required and must be non-empty.
- `repo` and `provider` are optional. Omit them for a repository-neutral scratch
  session; do not substitute a repository ID field.
- `project_id` optionally targets an existing accessible Project. Discover IDs with
  `GET /v3/organizations/:orgId/projects` using `sessions:read`. Project instructions
  are pinned at creation; `repo` and `target` remain explicit, compatible selections.
  Filter with `GET /v3/organizations/:orgId/sessions?project_id=<id>`.
- `idempotency_key` is an optional JSON body field, not an HTTP header. Reuse the
  same value when retrying the same logical create request.
- A new create returns HTTP 201. An idempotent replay returns HTTP 200 with the
  original session. Both return `session_id`, `url`, `status`, `session_policy`, and nullable `project_id`.
- Poll `GET /v3/organizations/:orgId/sessions/:sessionId`. Status is `running`,
  `exit` (execution completed), `error`, or `suspended` (cancelled/quota).
  Terminal responses may include `status`, `outcome`, `result`, `result_summary`,
  and `pr_url`. Lifecycle status is not task success: `exit` can have outcome `failure`
  or `action_required`. Require `outcome: success` and inspect the result; null is not success.
  The retrieved session's nullable `pr_url` is the
  pull or merge request URL when one exists; it is not part of the create response.
- Terminal status fields: once `status` leaves `running`, the session carries
  `finished_at`, `result`, `result_summary`, `outcome`, `pr_url`, `pr_title`,
  `cost_usd`, and `usage`; failures also fill `error_class`, `reason_code`,
  `diagnostic_message`, `failure_stage`, `failure_diagnostics`, and `root_cause`.
- Messages: `GET /v3/organizations/:orgId/sessions/:sessionId/messages` lists the
  conversation, cursor-paginated — pass the previous response's `end_cursor` as
  `after`. `POST` to the same path sends a follow-up instruction.

## Common endpoints

```
GET  /v3/organizations                                # list workspaces
GET  /v3/organizations/:orgId/projects                # discover existing projects
POST /v3/organizations/:orgId/sessions                # start a Reason session
GET  /v3/organizations/:orgId/sessions                # list sessions
GET  /v3/organizations/:orgId/sessions/:sessionId     # retrieve a session
GET  /v3/organizations/:orgId/sessions/:sessionId/messages  # list messages (cursor: after)
POST /v3/organizations/:orgId/sessions/:sessionId/messages  # send a follow-up
GET  /v3/organizations/:orgId/repositories            # list enabled repositories
GET  /v3/organizations/:orgId/git-plugins             # list GitHub plugins
```

## Notes

- This file lives at https://reasonmachines.com/llms.txt and is the canonical machine-readable
  entry point for agents. Read it first.