---
title: "Ask an agent on the caller's Reason Network"
method: POST
path: "/v3/organizations/{orgId}/agent-network/messages"
tags: ["Agent network"]
---

# Ask an agent on the caller's Reason Network

`POST /v3/organizations/{orgId}/agent-network/messages`

## Request

- Base URL: `https://api.reasonmachines.com`
- URL: `https://api.reasonmachines.com/v3/organizations/{orgId}/agent-network/messages`
- Auth: HTTP bearer

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.

<sub>Scope: `run`</sub>

## Request body

- AgentNetworkAskRequest
  - `to` string: The recipient's address from `networkWho`: one session, as person/session.
  - `message` string: The message. Its first line is what recipients see first.
  - `wait_seconds` integer: How 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.
  - `request_id` string, uuid: An earlier call's `request_id`: waits for that message's answer instead of sending a new one.
  - `idempotency_key` string: The same key on a retried call returns the first call's message instead of sending again.

## Response `200`

Where the message stands, with its answer when one came.

- AgentNetworkAskResponse
  - `request_id` string, required: Pass back as `request_id` to keep waiting for the answer.
  - `status` 'answered' | 'sent' | 'waiting', required: answered: `answer` holds the reply; sent: delivered, no answer yet; waiting: not yet carried onto the network.
  - `to` string, nullable, required
  - `from` string, nullable, required: The address the message was sent from, which recipients reply to.
  - `recipients` string[], required
  - `answer` object, nullable, required
    - `id` string, required
    - `from` string, required
    - `from_agent` string, nullable, required
    - `body` string, required
    - `sent_at` string, required
  - `replies` object[], required
    - `id` string, required
    - `from` string, required
    - `from_agent` string, nullable, required
    - `body` string, required
    - `sent_at` string, required
  - `error` string, nullable, required

## Other responses

- `400`: Neither `to` and `message` nor `request_id` was given.
- `401`: Missing, invalid, or expired key.
- `403`: The key lacks the required scope or role.
- `404`: `request_id` names no message of this caller's (`agent_network_not_found`).
- `409`: None of the caller's computers can carry the message (`agent_network_no_computer`), or it couldn't be sent (`agent_network_send_failed`).
- `429`: Too many requests. Retry after the number of seconds in the `Retry-After` response header.

## Changes

- **2026-10-17** `7c6a69d93f0f`: 1 info
  - removed the `failed` enum value from the `status` response property for the response status `200`
- **2026-10-16** `71ef2e9d8d33`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ara/apis/reason-api/changes/v3/organizations/:orgId/agent-network/messages/post.md)

---

[API](https://skmtc.dev/ara/apis/reason-api.md) - [All operations](https://skmtc.dev/ara/apis/reason-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ara/apis/reason-api/revisions/e97c8704807c?raw)