Are responses cached?

No. Every response is Cache-Control: no-store, so what you read is current.

Send a message

Q: Which scope does this need?

agent:message. A token without it gets 403 with requiredScope in the body. GET /me shows a token's scopes.

POST/api/v1/agent/messages

Message your agent exactly as the dashboard chat does, and optionally hold the request open for the reply.

Last updated 28 September 2026

curl -X POST -H "Authorization: Bearer $REVNU_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"text":"What did we ship this week?","waitSeconds":90,"clientRequestId":"weekly-1"}' \
  https://revnu.com/api/v1/agent/messages

Body

Field	Type	Meaning
`text`	string, required	Up to 4,000 characters.
`clientRequestId`	string	Up to 128 characters of `A-Za-z0-9_.:-`. A retry with the same id returns the original `requestId`. Never reuse an id after a `failed` message; send again with a new one.
`waitSeconds`	integer, 0 to 120	Hold the request until the agent has replied and finished the turn, or failed.
`interrupt`	boolean, default `true`	A new message stops the agent's running turn. Send `false` to leave unfinished work alone: while this token's newest message is still queued or running, nothing is sent and the response names that request with `notSent: true`.
`queue`	boolean, default `false`	Send `true` to hand over another job without stopping the running one: the message is sent and the agent starts it once its current work is done. Use it when your software sends several jobs in a row, such as one list of companies per market. It stays `queued` for up to six hours while earlier work runs, then counts as `failed`. Cannot be combined with `interrupt`.

Responses

Code	Meaning
202	`{ requestId, deduplicated, notSent?, message? }`. Queued; poll the message. With `waitSeconds`, `message` is the last state seen, and `waitEnded` (`unauthorized` or `poll_failed`) says when the wait stopped early. An `unauthorized` stop carries no `message`.
200	Only with `waitSeconds`: `message` is terminal and `replies` is filled.
400	Missing or empty `text`, `text` over 8,000 bytes, a non-string client id, a non-boolean `interrupt` or `queue`, `queue` together with `interrupt`, or a `waitSeconds` outside 0 to 120.
409	`text` over 4,000 characters, or a client id with characters outside `A-Za-z0-9_.:-`.

With interrupt: false and an unfinished earlier message, either code can carry notSent: true: requestId and message are then the earlier request's, and nothing new was sent.

Agents: this page is also markdown at /docs/agent-messages.md, answers Accept: text/markdown, and is listed in /docs/llms.txt.

Frequently Asked Questions

`agent:message`. A token without it gets `403` with `requiredScope` in the body. `GET /me` shows a token's scopes.