curl --request POST \
--url https://api.reasonmachines.com/v3/organizations/{orgId}/agent-network/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"to": "<string>",
"message": "<string>",
"wait_seconds": 150,
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>"
}
'import requests
url = "https://api.reasonmachines.com/v3/organizations/{orgId}/agent-network/messages"
payload = {
"to": "<string>",
"message": "<string>",
"wait_seconds": 150,
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<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({
to: '<string>',
message: '<string>',
wait_seconds: 150,
request_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
idempotency_key: '<string>'
})
};
fetch('https://api.reasonmachines.com/v3/organizations/{orgId}/agent-network/messages', 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}/agent-network/messages",
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([
'to' => '<string>',
'message' => '<string>',
'wait_seconds' => 150,
'request_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'idempotency_key' => '<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}/agent-network/messages"
payload := strings.NewReader("{\n \"to\": \"<string>\",\n \"message\": \"<string>\",\n \"wait_seconds\": 150,\n \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<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}/agent-network/messages")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"to\": \"<string>\",\n \"message\": \"<string>\",\n \"wait_seconds\": 150,\n \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reasonmachines.com/v3/organizations/{orgId}/agent-network/messages")
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 \"to\": \"<string>\",\n \"message\": \"<string>\",\n \"wait_seconds\": 150,\n \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"request_id": "<string>",
"status": "answered",
"to": "<string>",
"from": "<string>",
"recipients": [
"<string>"
],
"answer": {
"id": "<string>",
"from": "<string>",
"from_agent": "<string>",
"body": "<string>",
"sent_at": "<string>"
},
"replies": [
{
"id": "<string>",
"from": "<string>",
"from_agent": "<string>",
"body": "<string>",
"sent_at": "<string>"
}
],
"error": "<string>"
}{
"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"
}
}Ask an agent on the caller's Reason Network
Sends a message to an agent on the caller’s Reason Network, carried by one of the caller’s own computers online running Reason, as send_message is, and returns its answer when it comes within wait_seconds (default 25; a call is held at most 45 s). Recipients see it from <person>/<client>. Pass request_id to keep waiting for an earlier message’s answer. Answers 409 agent_network_no_computer when none of the caller’s computers is online, and 409 agent_network_send_failed, with request_id and message, when the computer carrying it couldn’t send it.
runcurl --request POST \
--url https://api.reasonmachines.com/v3/organizations/{orgId}/agent-network/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"to": "<string>",
"message": "<string>",
"wait_seconds": 150,
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>"
}
'import requests
url = "https://api.reasonmachines.com/v3/organizations/{orgId}/agent-network/messages"
payload = {
"to": "<string>",
"message": "<string>",
"wait_seconds": 150,
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<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({
to: '<string>',
message: '<string>',
wait_seconds: 150,
request_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
idempotency_key: '<string>'
})
};
fetch('https://api.reasonmachines.com/v3/organizations/{orgId}/agent-network/messages', 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}/agent-network/messages",
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([
'to' => '<string>',
'message' => '<string>',
'wait_seconds' => 150,
'request_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'idempotency_key' => '<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}/agent-network/messages"
payload := strings.NewReader("{\n \"to\": \"<string>\",\n \"message\": \"<string>\",\n \"wait_seconds\": 150,\n \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<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}/agent-network/messages")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"to\": \"<string>\",\n \"message\": \"<string>\",\n \"wait_seconds\": 150,\n \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.reasonmachines.com/v3/organizations/{orgId}/agent-network/messages")
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 \"to\": \"<string>\",\n \"message\": \"<string>\",\n \"wait_seconds\": 150,\n \"request_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"request_id": "<string>",
"status": "answered",
"to": "<string>",
"from": "<string>",
"recipients": [
"<string>"
],
"answer": {
"id": "<string>",
"from": "<string>",
"from_agent": "<string>",
"body": "<string>",
"sent_at": "<string>"
},
"replies": [
{
"id": "<string>",
"from": "<string>",
"from_agent": "<string>",
"body": "<string>",
"sent_at": "<string>"
}
],
"error": "<string>"
}{
"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
Your Reason API key from Settings › API keys. 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
Organization id or slug. Resolve it with GET /v3/self.
Body
The recipient's address from networkWho: one session, as person/session.
1 - 300The message. Its first line is what recipients see first.
1 - 30000How long to wait for the answer (default 25). One call waits at most 45 seconds; with no answer by then, request_id passed back keeps waiting. 0 returns once the message is sent.
0 <= x <= 300An earlier call's request_id: waits for that message's answer instead of sending a new one.
^([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)$The same key on a retried call returns the first call's message instead of sending again.
1 - 200Response
Where the message stands, with its answer when one came.
Pass back as request_id to keep waiting for the answer.
answered: answer holds the reply; sent: delivered, no answer yet; waiting: not yet carried onto the network.
answered, sent, waiting The address the message was sent from, which recipients reply to.
Show child attributes
Show child attributes
Show child attributes
Show child attributes

