Create a Reason

Create a Reason

curl --request POST \
  --url https://api.reasonmachines.com/v3/organizations/{orgId}/reasons \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

import requests

url = "https://api.reasonmachines.com/v3/organizations/{orgId}/reasons"

payload = { "name": "<string>" }
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({name: '<string>'})
};

fetch('https://api.reasonmachines.com/v3/organizations/{orgId}/reasons', 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}/reasons",
  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([
    'name' => '<string>'
  ]),
  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}/reasons"

	payload := strings.NewReader("{\n  \"name\": \"<string>\"\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}/reasons")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.reasonmachines.com/v3/organizations/{orgId}/reasons")

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  \"name\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "mine": true,
  "visibility": "workspace",
  "main": true,
  "appearance": {
    "color": "black",
    "eyes": "pills",
    "glasses": "none",
    "accessory": "none"
  },
  "session_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": "prompt_required"
}

{
  "error": "missing_bearer",
  "message": "Authorization required"
}

{
  "error": "missing_scope",
  "required_scope": "sessions:read"
}

{
  "error": {
    "type": "rate_limited",
    "message": "This API key exceeded its request-rate limit"
  }
}

POST

organizations

{orgId}

reasons

Create a Reason

curl --request POST \
  --url https://api.reasonmachines.com/v3/organizations/{orgId}/reasons \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

import requests

url = "https://api.reasonmachines.com/v3/organizations/{orgId}/reasons"

payload = { "name": "<string>" }
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({name: '<string>'})
};

fetch('https://api.reasonmachines.com/v3/organizations/{orgId}/reasons', 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}/reasons",
  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([
    'name' => '<string>'
  ]),
  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}/reasons"

	payload := strings.NewReader("{\n  \"name\": \"<string>\"\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}/reasons")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.reasonmachines.com/v3/organizations/{orgId}/reasons")

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  \"name\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "mine": true,
  "visibility": "workspace",
  "main": true,
  "appearance": {
    "color": "black",
    "eyes": "pills",
    "glasses": "none",
    "accessory": "none"
  },
  "session_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "error": "prompt_required"
}

{
  "error": "missing_bearer",
  "message": "Authorization required"
}

{
  "error": "missing_scope",
  "required_scope": "sessions:read"
}

{
  "error": {
    "type": "rate_limited",
    "message": "This API key exceeded its request-rate limit"
  }
}

Authorizations

Authorization

string

header

required

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, network:read, network:write, automations:read, automations:write, agent_auth:read. network:read and network:write are opt-in, excluded from default keys. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).

Path Parameters

orgId

string

required

Organization id or slug. Resolve it with GET /v3/self.

Body

application/json

A new named Reason. Without appearance it wears the default bot (black, pill eyes, no glasses, no accessory).

name

string

required

The name the Reason is listed under in the app, for example Release notes. Surrounding spaces are dropped and inner runs of spaces become one.

Required string length: 1 - 80

appearance

object

How the Reason's bot avatar looks in the app. Purely visual; it changes nothing the agent does.

Show child attributes

Response

The new Reason.

A long-running agent conversation the person keeps: their main Reason or a named one. Sessions it starts are filed under it.

string<uuid>

required

Reason id. Pass it as reasonId to the other Reason tools.

name

string

required

Display name. The main Reason is always called Reason.

user_id

string<uuid>

required

The owner, the only person who can open, rename or archive it.

mine

boolean

required

True when the caller owns this Reason.

visibility

enum<string>

required

workspace: every member sees it in their list; private: only its owner does.

Available options:

workspace,

private

main

boolean

required

True for the person's main Reason, which is always listed and is never renamed or archived.

appearance

object

required

How the Reason's bot avatar looks in the app. Purely visual; it changes nothing the agent does.

Show child attributes

session_id

string | null

required

Its conversation Session once it has been opened, and only on the caller's own Reasons; null otherwise. Use it with sendSessionMessage and listSessionConversation.

created_at

string<date-time>

required

updated_at

string<date-time>

required

Connect

Endpoints

Authorizations

Path Parameters

Body

Response