# Reason

> 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.ai; programmatic per-user access is available through the HTTP API.

If you are an AI agent: use the public HTTP API below instead of scraping this
website. Public customer MCP is retired. Do not connect to `/mcp/ara`.

## HTTP API

- Base URL: `https://api.reasonmachines.ai`
- 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.ai/healthz`
- All responses are JSON.
- Credential reference: https://docs.reasonmachines.ai/api-reference/account/verify-credentials
- Full endpoint reference: https://docs.reasonmachines.ai/api-reference
- Public MCP (`GET`/`POST` `/mcp/ara`) returns 410. Use `/v3` with a Reason API
  key instead.

## 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`, and nullable `project_id`.
- Poll `GET /v3/organizations/:orgId/sessions/:sessionId`. Status is `running`,
  `exit` (completed successfully), `error`, or `suspended` (cancelled/quota).
  Only `exit` is successful. 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.

## 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
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.ai/llms.txt and is the canonical machine-readable
  entry point for agents. Read it first.