curl --request POST \
--url https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Fix the flaky test in src/auth/session.test.ts and add a regression case.",
"repo": "acme/web",
"provider": "github",
"tags": [
"ci",
"tests"
]
}
'import requests
url = "https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions"
payload = {
"prompt": "Fix the flaky test in src/auth/session.test.ts and add a regression case.",
"repo": "acme/web",
"provider": "github",
"tags": ["ci", "tests"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: 'Fix the flaky test in src/auth/session.test.ts and add a regression case.',
repo: 'acme/web',
provider: 'github',
tags: ['ci', 'tests']
})
};
fetch('https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'Fix the flaky test in src/auth/session.test.ts and add a regression case.',
'repo' => 'acme/web',
'provider' => 'github',
'tags' => [
'ci',
'tests'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions"
payload := strings.NewReader("{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"session_policy": {
"version": 1,
"mode": "standard",
"components": {
"memoryRead": true,
"memoryWrite": true,
"skills": true,
"inheritedInstructions": true,
"integrations": true,
"secretInjection": true
},
"workspaceOwnership": "ara-managed"
},
"session_id": "<string>",
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"status": "running"
}{
"session_id": "ses_91af3c",
"project_id": null,
"url": "https://reasonmachines.com/agents/ses_91af3c",
"status": "running"
}{
"error": "prompt_required"
}{
"error": "unauthorized"
}{
"error": "quota_exhausted",
"message": "Monthly sandbox minutes exceeded."
}Create a session
Opens a new session from a prompt. Optional project_id binds an accessible existing Project and pins its instructions. Use GET /projects to discover IDs; repo and target remain explicit selections and must be compatible with that Project. repo is optional: provide one to bind the initial checkout, or omit it for a repository-neutral start. If the running Brain later discovers an exact connected repository, Ara attaches it and continues the original task under this Session ID instead of creating another user task. The session starts immediately and runs asynchronously: poll GET /sessions/{id} for status and GET /sessions/{id}/events for incremental live output.
runcurl --request POST \
--url https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Fix the flaky test in src/auth/session.test.ts and add a regression case.",
"repo": "acme/web",
"provider": "github",
"tags": [
"ci",
"tests"
]
}
'import requests
url = "https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions"
payload = {
"prompt": "Fix the flaky test in src/auth/session.test.ts and add a regression case.",
"repo": "acme/web",
"provider": "github",
"tags": ["ci", "tests"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: 'Fix the flaky test in src/auth/session.test.ts and add a regression case.',
repo: 'acme/web',
provider: 'github',
tags: ['ci', 'tests']
})
};
fetch('https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'Fix the flaky test in src/auth/session.test.ts and add a regression case.',
'repo' => 'acme/web',
'provider' => 'github',
'tags' => [
'ci',
'tests'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions"
payload := strings.NewReader("{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reasonmachines.ai/v3/organizations/{orgId}/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"Fix the flaky test in src/auth/session.test.ts and add a regression case.\",\n \"repo\": \"acme/web\",\n \"provider\": \"github\",\n \"tags\": [\n \"ci\",\n \"tests\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"session_policy": {
"version": 1,
"mode": "standard",
"components": {
"memoryRead": true,
"memoryWrite": true,
"skills": true,
"inheritedInstructions": true,
"integrations": true,
"secretInjection": true
},
"workspaceOwnership": "ara-managed"
},
"session_id": "<string>",
"project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"status": "running"
}{
"session_id": "ses_91af3c",
"project_id": null,
"url": "https://reasonmachines.com/agents/ses_91af3c",
"status": "running"
}{
"error": "prompt_required"
}{
"error": "unauthorized"
}{
"error": "quota_exhausted",
"message": "Monthly sandbox minutes exceeded."
}Authorizations
Your Reason API key from Settings > API. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, knowledge:read, memory:read, memory:write, skills:read, skills:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, automations:read, automations:write, agent_auth:read. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:debug is privileged: it expands diagnostic session events only for organization owners/admins.
Path Parameters
Organization id or slug. Resolve it with GET /v3/self.
Body
What the agent should do. Maximum 256 KiB when UTF-8 encoded.
Session component preset. Standard retains configured capabilities; isolated removes ambient memory, skills, instructions, integrations, and secret injection. Defaults to standard unless the legacy benchmark profile is supplied.
standard, isolated Filesystem persistence owner, independent of mode. Externally-managed requires an explicit headless project_root. Defaults to ara-managed unless the legacy benchmark profile is supplied.
ara-managed, externally-managed Coding-only trial on an explicit headless project_root. Disables durable memory, skills, external tools, inherited secrets, and additional messages. Each trial requires a fresh Session. The externally managed ephemeral workspace is never captured or restored by Ara; current-trial conversation and compaction are retained.
"coding-benchmark-v1"Existing Project ID from GET /projects or POST /projects. Standard sessions pin its instructions. Isolated externally-managed headless project_root sessions may use a resource-free project for grouping only; inherited instructions and durable learning stay disabled. Repository and machine selection remain explicit through repo and target.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Explicit Hands machine target. Device targets require devices:use plus an owned, eligible root. Headless targets use externally provisioned compute and require the central relay; unavailable targets never fall back to cloud.
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes
Optional initial connected GitHub repository path in owner/name form. Omit it for a scratch session.
Source-control provider for the repo. GitHub is the only supported provider.
github Concrete model id from GET /agent-auth/models. Omit or use auto to inherit the workspace default.
Optional reasoning effort override for the selected model.
minimal, low, medium, high, xhigh, max Physical execution policy. adaptive (default) starts with Brain and lazily acquires Hands when work needs a shell, files, browser, or sandbox. brain_only permanently forbids physical Hands and secret materialization for this Session and all of its continuation Attempts; independently created Sessions keep their own policy.
adaptive, brain_only Requests a durable noninteractive completion envelope. The agent may return success, failure, or action_required plus any JSON result; executor/runtime failures remain separate lifecycle errors.
"run_outcome"At most 50 tags; each tag is at most 100 UTF-8 bytes.
Existing branch to check out and work on; commits land on this branch. Created off the default branch if it does not exist yet. Mutually exclusive with pr_number and ref.
Continue an existing pull request: the agent checks out its head branch and commits back onto it (no new PR). GitHub only. Mutually exclusive with branch and ref.
x >= 1Commit SHA, tag, or branch to snapshot: the agent starts a fresh working branch from this ref and opens a new PR. Mutually exclusive with branch and pr_number.
Pull-request base branch for a ref snapshot. Use this when the snapshot belongs to a non-default integration branch. Valid only with ref; the resolved ref remains the immutable checkout and publication base.
Session-scoped environment variables, injected into the agent's shell for this session only (and its follow-up turns). Names must match ^[A-Za-z_][A-Za-z0-9_]*$ and may not use reserved inference names; at most 64 keys, 32 KB per value, 256 KB total. Values override personal or workspace secrets of the same name, are write-only (never returned by any read endpoint), and are redacted from logs and transcripts.
Show child attributes
Show child attributes
Idempotent create: a retried POST with the same key returns the original session instead of creating a duplicate.
Optional task authorization shared by automatic continuations and delegated sessions. New tasks have no deadline by default; zero explicitly selects no deadline. Positive durations range from one minute to 1,000 hours. Wall clock starts at execution admission and includes recovery waits. Spending reserves concurrent inference costs before dispatch; omitted/null spending retains account limits.
Show child attributes
Show child attributes
Response
Idempotent replay of the original session.
Server-resolved immutable Session policy. Enabled components remain subject to normal permissions and configuration.
Show child attributes
Show child attributes
Project containing the session, or null for an unassigned session.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Web URL to watch the session.
running, exit (completed), error, or suspended (cancelled/quota).
running, exit, error, suspended 
