# 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 <ara_api_key>`
- Mint a key from Reason Settings → Developers (the Code / API keys picker). A
  new key includes the ordinary public scopes for this walkthrough.
- 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.
- Quickstart: https://docs.reasonmachines.ai/api-quickstart
- Full endpoint reference: https://docs.reasonmachines.ai/api-reference
- Public MCP (`GET`/`POST` `/mcp/ara`) returns 410. Use `/v3` with an `ara_`
  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 an Ara 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.

## 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.com/llms-full.txt

### Product

- [Get Reason](https://reasonmachines.com/download.md): Reason for Mac, the terminal, and the browser. Sign in once and your sessions follow you.

### Company

- [Reason Index](https://reasonmachines.com/blog.md): Product updates, engineering deep-dives, and how teams ship with Reason.
- [Changelog](https://reasonmachines.com/news.md): What's new in Reason: features, fixes, and infrastructure.
- [Contact Reason](https://reasonmachines.com/contact.md): Get in touch with the Reason Machines team.
- [Building the future of coding.](https://reasonmachines.com/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, and opinionated enough to make the whole loop better each time it runs.

### Blog

- [Software Engineering on autopilot. Reason 1.0](https://reasonmachines.com/blog/ara-on-the-web.md): Introducing Reason 1.0. Describe the work, follow the progress, and review the result—on web, desktop, and mobile.
- [Reason for macOS](https://reasonmachines.com/blog/ara-for-macos.md): Run cloud sessions and let Reason work with your local files, tools, and ports.
- [Rust harness wars: grok-build vs codex](https://reasonmachines.com/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.
- [Deal for YC founders](https://reasonmachines.com/blog/yc.md): Current and alumni YC companies redeem Reason credits through Bookface. Autonomous engineering for founders.
- [Building the software factory](https://reasonmachines.com/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.

### Use cases

- [Turn every alert into a closed loop](https://reasonmachines.com/use-cases/operations.md): Reason watches the systems you run, triages each signal against the playbook, and acts. What used to page a human at 3am now opens a verified pull request instead.
- [From issue to verified pull request, one context.](https://reasonmachines.com/use-cases/engineering.md): Reason reads the issue, reproduces it in an isolated workspace, writes the fix, and verifies it before asking for review. The whole sdlc runs in a single thread of context.
- [Point a question at the repo. Get a cited answer.](https://reasonmachines.com/use-cases/research.md): Reason runs an agentic research pass over a codebase or problem, traces the real call paths, and reports findings with a citation behind every claim. Each run also writes back what it learned, so the next one starts smarter.

### 简体中文

- [Reason：GitHub 自主软件工程师](https://reasonmachines.com/zh-hans.md): Reason 理解您的代码库、使用您的工具，并将清晰的需求转化为经过验证、可供审查的代码变更。
- [Reason 企业版](https://reasonmachines.com/zh-hans/enterprise.md): Reason 在您的云和安全控制范围内交付经过验证的拉取请求，并为每次运行保留签名记录。
- [面向工程团队的 Reason](https://reasonmachines.com/zh-hans/use-cases/engineering.md): Reason 在一个上下文中读取问题、复现问题、编写修复并完成验证，然后再请求代码审查。