Skip to main content

​
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. Programmatic access uses the HTTP API and Reason MCP documented here.

​
Start here

Verify credentials

Confirm your API key, scopes, and organization with GET /v3/self.

API reference

Full OpenAPI reference for sessions, projects, secrets, skills, and more.

​
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
  • 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

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.