Verify credentials

Returns the principal behind the current credential, its granted scopes, and the organization it can act on. Call this first to discover your org_id and available capabilities.

REST quickstart

1. Create a key at reasonmachines.com/customize?tab=api (Settings > API). Send it only in Authorization: Bearer <key>, never in a URL.
2. Call this endpoint and keep the returned org_id. Creating and polling a session requires run and sessions:read.
3. Optionally discover repositories with GET /v3/organizations/{orgId}/repositories (repos:read) and Projects with GET /v3/organizations/{orgId}/projects (sessions:read). Use an accessible Project ID; selecting a Project does not automatically select its repository or execution target.
4. POST a prompt to /v3/organizations/{orgId}/sessions. Set completion_mode: run_outcome for unattended work and an idempotency_key in the JSON body. Retrying the same task must reuse the same key and project/target/policy. HTTP 201 creates; HTTP 200 replays.
5. Poll the returned session ID with GET until status leaves running. Lifecycle exit does not prove success: inspect outcome, result, result_summary, and diagnostics. Only outcome success is a successful task; failure, action_required and null need handling. Follow Retry-After on HTTP 429.

Runnable Node.js example

Download api-session.mjs, review it, and run it with Node.js 20 or newer. It creates real work that may incur usage. Set REASON_API_KEY, REASON_PROMPT, and a stable REASON_IDEMPOTENCY_KEY in your environment, then run node api-session.mjs. Optional REASON_REPO and REASON_PROJECT_ID select resources explicitly. The example exits nonzero for failed, suspended, unresolved, or action-required tasks and times out after ten minutes without cancelling the remote session.

MCP is a separate client connection

For an MCP client, connect to https://mcp.reasonmachines.com/mcp using that client's supported OAuth setup. See Connect over MCP for the commands. The REST workflow above uses the HTTP API and does not require installing an MCP client.

_{Auth: any valid API key (no scope)}