# Reason

OpenAPI JSON: https://api.reasonmachines.company/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.company; programmatic per-user access is available through the HTTP API.

## Public website

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.

- Complete public content: https://reasonmachines.company/llms-full.txt
- Canonical page inventory: https://reasonmachines.company/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.company`
- 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.company/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.company/api-reference/account/verify-credentials
- Full endpoint reference: https://docs.reasonmachines.company/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.company/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.company/mcp`, then /mcp to authenticate.
- Codex: `codex mcp add reason --url https://mcp.reasonmachines.company/mcp`, then `codex mcp login reason`.
- Publisher-owned Claude and Codex plugins: https://github.com/reason-machines/reason-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.company/llms.txt and is the canonical machine-readable
  entry point for agents. Read it first.

## Pages

Every page below is also available as clean Markdown: append `.md` to the URL, or send `Accept: text/markdown`. The entire site as one file: https://reasonmachines.company/llms-full.txt

### Blog

- [Reason for macOS](https://reasonmachines.company/blog/ara-for-macos.md): Run cloud sessions and let Reason work with your local files, tools, and ports.
- [Introducing Reason Agent 1.0](https://reasonmachines.company/blog/reason-agent-deepswe.md): Our first results on DeepSWE v1.1. Competitive with frontier harnesses, with up to 39% lower median solving time against our benchmark baseline.
- [Rust harness wars: grok-build vs codex](https://reasonmachines.company/blog/rust-harness-wars.md): We cloned xAI's grok-build and OpenAI's codex and read both line by line, twenty subsystems each, to see where two labs building the same coding agent actually diverge.
- [Reason for Startups](https://reasonmachines.company/blog/yc.md): Current and alumni YC companies get $1,000 in credits to start coding. Open the Reason deal on Bookface and follow the redemption instructions to claim them.
- [Building the software factory](https://reasonmachines.company/blog/about.md): We are building the software factory we wanted as engineers: fast enough to keep up with ideas, careful enough to trust with real repositories.

### Legal

- [Terms of Service](https://reasonmachines.company/terms-of-service.md): Terms governing Reason Machines websites, applications, APIs, cloud sessions, and local-runtime controls.
- [Privacy Policy](https://reasonmachines.company/privacy-policy.md): How Reason Machines collects, uses, shares, retains, and deletes information.
- [Account Deletion](https://reasonmachines.company/delete-account.md): How to request deletion of your Reason account and associated data.

### 简体中文

- [Reason Agent：自主软件工程师 · Reason Machines](https://reasonmachines.company/zh-hans.md): Reason Machines 的 Reason Agent 是自主 AI 软件工程师和云端编程智能体。连接 GitHub、分配问题，即可自动交付附有验证证据的拉取请求。
- [服务条款](https://reasonmachines.company/zh-hans/terms-of-service.md): 适用于 Reason Machines 网站、应用、API、云端会话及本地运行时控制的条款。
- [隐私政策](https://reasonmachines.company/zh-hans/privacy-policy.md): Reason Machines 如何收集、使用、共享、保留和删除信息。
- [删除账户](https://reasonmachines.company/zh-hans/delete-account.md): 如何申请删除您的 Reason 账户及相关数据。
- [macOS 版 Reason](https://reasonmachines.company/zh-hans/blog/ara-for-macos.md): 运行云端会话，让 Reason 使用你的本地文件、工具和端口开展工作。
- [介绍 Reason Agent 1.0](https://reasonmachines.company/zh-hans/blog/reason-agent-deepswe.md): 我们在 DeepSWE v1.1 上的首批结果已能与前沿智能体框架竞争。相较于基准对照，解题时间中位数最多降低 39%。
- [Rust 智能体框架之争：grok-build 与 codex](https://reasonmachines.company/zh-hans/blog/rust-harness-wars.md): 我们克隆了 xAI 的 grok-build 和 OpenAI 的 codex，逐行阅读双方各二十个子系统，探究两个实验室在构建同类编程智能体时究竟有何不同。
- [面向初创企业的 Reason](https://reasonmachines.company/zh-hans/blog/yc.md): 在读及往届 YC 公司可领取价值 1,000 美元的额度，用于开始编程。在 Bookface 打开 Reason 优惠页面，按照兑换说明领取。
- [构建软件工厂](https://reasonmachines.company/zh-hans/blog/about.md): 我们正在构建工程师心中理想的软件工厂：快到能跟上想法，也足够严谨，值得托付真实的代码仓库。