curl --request POST \
--url https://api.reasonmachines.com/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.com/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.com/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.com/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.com/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.com/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.com/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_bodyCreate 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.com/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.com/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.com/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.com/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.com/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.com/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.com/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_bodyAuthorizations
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.
Defaults to standard for normal workflows, including API sessions targeting a local Mac. Standard retains configured capabilities and supports follow-up messages. Use isolated only as an explicit override for benchmark trials: it disables follow-up messages and removes ambient memory, skills, instructions, integrations, and secret injection. Each isolated trial requires a fresh session. Explicitly supplying the legacy benchmark_profile also selects isolated mode.
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"Benchmark-only sync-yield runtime. Requires isolated mode and an externally managed headless project_root. Advertises exactly Bash and ViewImage.
"runtime/reason-sync-yield-v1"Allowlisted evaluation runtime. Supports isolated stateless trials and standard full-product sessions while keeping the provider-visible surface at exactly Bash and ViewImage.
"runtime/reason-capability-shell-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. A headless Device runs one Session at a time: while it is running another, create returns 409 device_busy. A machine target (set exactly one of name or id) also requires devices:use; it runs on any eligible worker of that Machine with an externally-managed project_root workspace, and waits FIFO for a free worker (up to 30 minutes, or the execution budget) instead of failing when every worker is busy. It returns 409 machine_unavailable when the Machine has no online eligible worker.
- Option 1
- Option 2
- Option 3
- Option 4
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 shared session spending ceiling in RCUs, including models, machines and manual desktop time. Decimal string with up to nine fractional digits. Null retains wallet limits. Automatic delegated sessions share their source ceiling.
^(0|[1-9]\d{0,6})(\.\d{1,9})?$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.
^([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)$Lifecycle state, not task success: running, exit (execution completed), error (execution failed), or suspended (cancelled/quota). An exit can have outcome failure or action_required. Check outcome, result, and diagnostics before treating work as successful.
running, exit, error, suspended Server-resolved immutable Session policy. Enabled components remain subject to normal permissions and configuration.
Show child attributes
Show child attributes