Skip to main content
POST
Send a message on the workspace's Reason Network

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
to
string
required

"person/session" (or just "session").

Required string length: 1 - 300
message
string
required

The message, with the point in the first line.

Required string length: 1 - 30000
reply_to
string | null

Id of the message you are replying to.

Required string length: 1 - 100
notify
boolean | null

Also pop it up on that person's screen, for when they must act themselves (an approval, a decision). to may then be your own user's name, to reach them.

Response

What the network did with it, per recipient.

from
string | null
required

The address it went out from, which replies reach and land in check_inbox.

ids
string[]
required

The network's id for the message; a reply names it as reply_to.

recipients
object[]
required
unread
object | null
required

Messages to the caller's agent it hasn't read, and who sent them, as check_inbox returns them; null when there are none.

note
string | null
required