Talk to Your Agent

A message through the API does exactly what typing into the dashboard chat does. Revnu reads it, does the work with the same tools and Memory, and replies in one or more bubbles. Anything it wants approved lands in the review queue.

One call, with the reply inline

Pass waitSeconds (up to 120) and the request stays open until the message is done: Revnu has replied or failed and any background research it started has been reported. Replies usually land in well under a minute. Real work, such as researching a list, can take longer.

curl -X POST -H "Authorization: Bearer $REVNU_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"text":"Which leads replied this week?","waitSeconds":90,"clientRequestId":"weekly-replies-2026-42"}' \
  https://revnu.com/api/v1/agent/messages

A 200 carries the finished message with its replies. If the wait runs out you get 202 with the last observed state and a requestId to keep polling.

Or post and poll

Without waitSeconds the POST returns 202 immediately. Poll GET /agent/messages/{requestId} every few seconds. status moves queued → running → replied, or ends failed with a failure message.

Progress bubbles can arrive in replies while it is still running. replied means the turn is over. Long research can keep running after it as a background task, listed in backgroundTasks; done turns true once that result is reported too. The poll returns the newest bubbles.

Safe retries

Pass clientRequestId (up to 128 characters of A-Za-z0-9_.:-). A retried POST with the same id returns the original requestId with deduplicated: true instead of sending a second message. Make the id from the job itself, such as import-eu-fintech-2026-10-15, so a crash and restart sends the same id.

A failed message should be re-sent with a new id. Reusing the old one returns the failed request.

Interrupts

A new message stops whatever Revnu is still doing for this token and starts on the new one. That's right when you mean "stop, do this instead". It's wrong when a script fires jobs one after another. Two fields change it:

queue and interrupt can't be combined. The MCP tool ask_revnu defaults to interrupt: false, so an assistant can't stop work by accident. The CLI's revnu agent message sends with the default, and takes --queue.

Many jobs in a row

To hand over several jobs, such as one list of companies per market, send each with queue: true and its own clientRequestId:

const jobs = [
  { id: "markets-2026-10-15-uk", text: "Find 20 UK fintechs with 50 to 200 staff that sell to SMBs." },
  { id: "markets-2026-10-15-de", text: "Find 20 German fintechs with 50 to 200 staff that sell to SMBs." },
];
for (const job of jobs) {
  const res = await fetch("https://revnu.com/api/v1/agent/messages", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.REVNU_API_TOKEN}`, "content-type": "application/json" },
    body: JSON.stringify({ text: job.text, clientRequestId: job.id, queue: true }),
  });
  const { requestId } = await res.json();
  saveRequestId(job.id, requestId); // poll each later
}

Each job runs to the end before the next starts. A queued message waits up to six hours behind earlier work, then counts as failed, so don't queue a day's worth at once.

A worked rate example

Say you have 40 jobs. The agent-message limit is 30 calls a minute per token, and sending a message, polling a message and reading the thread all spend it. GET /agent/status is a read and spends the separate read limit of 300 a minute.

1. 1

   Send the jobs at 20 a minute

   The 40 jobs go out over two minutes. That leaves 10 message calls a minute spare.

2. 2

   Watch the account status

   While they run, poll GET /agent/status every 10 seconds. That's 6 reads a minute and touches nothing in the message budget.

3. 3

   Check each job

   Read GET /agent/messages/{requestId} for each job every minute or so, oldest first. Stop polling a job once done is true.

The jobs run one after another, so the batch takes as long as all 40 together. If each takes about five minutes, the last starts more than three hours after the first. Anything still waiting after six hours fails, so split a bigger batch across the day, or put several markets in one message.

Keep research jobs from sending anything

A message can't promise "research only". Whether Revnu's work goes out depends on What Needs Your Approval in Settings > Agent.

To be sure a batch of research jobs only produces leads and drafts, set Start Sequences, One-Off Emails, Connection Requests and Messages to Ask Me First before you send the batch. Drafts then wait as cards in the review queue until someone approves them.

To check whether Revnu is busy with anything on the account, including chat, Slack and scheduled work, read GET /agent/status: running is true while a turn is in progress.

Each token is its own conversation

Your dashboard and Slack threads are not visible through the API, and API messages do not appear in them. GET /agent/thread returns this token's conversation, newest first. Revnu sees each message as coming from API token "<label>", so give a bot or coding agent its own token and Revnu can tell it apart from you.

Status questions without side effects

A message is a request for work. Telling Revnu "status only, don't change anything" is an instruction it follows, not a permission it can't break. For a status bot, read the numbers directly, with a token that holds only read scopes:

Some answers only Revnu can give. There is no endpoint for how a sending inbox's warm-up is going or when it will start sending, and none for why a post failed. Ask Revnu with a message, which needs agent:message:

curl -X POST -H "Authorization: Bearer $REVNU_QUESTIONS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"text":"Are my sending inboxes ready to send yet? Which are still warming up?","waitSeconds":90,"interrupt":false}' \
  https://revnu.com/api/v1/agent/messages

interrupt: false means a question never stops a job this token started. If one is still running, nothing is sent and the response says notSent: true. The message is still a request Revnu can act on, so keep it to a question and use a separate token for it. A status bot that can also explain has the full setup.