API overview

Base URL, authentication, defaults, polling, and errors for the Reason HTTP API. Every endpoint is listed in the reference.

The Reason HTTP API creates and continues Sessions, reads their events, and manages the computers, secrets, skills and automations they use. Every endpoint is in the reference on the left.

​

Base URL

https://api.reasonmachines.com/v3

Organization-scoped paths start with /v3/organizations/{orgId}. Get orgId once from GET /v3/self, which returns org_id.

​

Authentication

Send an API key as a bearer token:

curl -fsS -H "Authorization: Bearer $REASON_API_KEY" https://api.reasonmachines.com/v3/self

A key carries scopes, and each endpoint names the scope it needs. Read Authentication and scopes for the full table and the other sign-in methods.

​

Start with these calls

Step	Endpoint
Confirm the key and get the organization	GET /v3/self
Create a Session	POST /v3/organizations/{orgId}/sessions
Read its status and events	GET /v3/organizations/{orgId}/sessions/{sessionId}/events
Send a follow-up	POST /v3/organizations/{orgId}/sessions/{sessionId}/messages
Cancel it	POST /v3/organizations/{orgId}/sessions/{sessionId}/cancel
List your computers	GET /v3/organizations/{orgId}/devices

​

Defaults

• A Session created without target runs in Reason’s cloud. Name a target to run on your computer.
• Session lists return newest first and exclude archived Sessions unless you pass status=archived or status=all.
• Work starts asynchronously. Creating a Session returns at once with its ID, so poll for its state.
• A Session’s outcome is the task result. status only says whether execution finished: a Session can end with status: exit and outcome: failure.

​

Polling, not streaming

Events are read by polling GET .../events with after_seq and wait_ms. Each call returns the events after your cursor, and with wait_ms it waits for the next one. Read Events reference for the cursor, duplicates and ordering.

​

Errors

Errors return a JSON body with an error object that has a type and a message. The status code tells you what to do:

Status	Meaning	What to do
400	The body is invalid, or a host or field is rejected	Fix the request; do not retry as is
401	The key is missing, expired or wrong	Check the key in Settings > API
403	The key lacks a scope, or your role is too low	Read missing_scope in the body, then grant that scope
404	The resource does not exist or you cannot see it	Check the ID
409	The request conflicts with current state	Read the reason in the body and retry after it changes
429	The key is rate-limited	Back off and retry later

Read the body before you retry. Do not widen a key’s scopes to get past an error that names a missing one.

​

Versions

This reference is version 3 of the API (info.version is 3.0.0). Deprecated operations say so in their description, and point to their replacement.