Recomma for agents

Most of what Recomma measures is something you act on through other tools — your site’s code, your CMS, an outreach list. So the product is built to be used by the agents you already work with, not only read on a screen. Here is how that works.

Start: what is missing

On a brand that is new, or whose figures look empty, get_setup comes before the brief. It walks the steps a brand needs before its readings mean much — a plan, the engines to sample, questions, enough recent answers, rivals, the site read, Google Analytics, a watch — and marks each one done, waiting, or to do.

A step to do says who can take it. The agent’s steps carry the tool call to make; a person’s carry the page to send them to, because a payment, a Google sign-in, and accepting questions that spend credits are a person’s to make. Waiting steps are the ones nobody can hurry — the crawl, the first sampling pass — and say so, so an agent does not retry them. measuring says whether answers are arriving in numbers worth quoting. Over REST it is /v1/agent/setup.

Tell: the brief

get_brief answers “what changed, and what do I do” in one call. It compares the last days days with the same span before and ranks what moved:

• questions you lost or gained ground on,
• rivals named more or less often,
• sites that started appearing in the answers (three times or more),
• fixes that were re-measured, and whether they worked,
• and the top open actions — by impact, and between equal impacts the lighter job first.

A move is listed only when the two readings’ 95% intervals do not overlap, so a question with six answers is counted as too thin to call rather than ranked as a drop. Every line carries the tool call to make next, so an agent reading it knows where to go without asking. The same brief is at recomma://brands/{brandId}/brief and over REST at /v1/agent/brief.

Wake: watches and webhooks

An agent that has to ask “did anything change?” every morning is a dashboard with extra steps. create_watch turns that around: say once what you want to hear about, and Recomma checks it after every sampling pass.

A watch fires when its condition turns true, then stays quiet until it has been false again — a drop that lasts a month is one event. A week too thin to read neither fires nor re-arms, and a watch that fired waits a day before it can fire again.

Every event goes to the brand’s event feed, which list_events reads with a cursor: pass the last answer’s nextCursor as after and you get only what is new. When the watch names a webhookUrl, the event is also POSTed there.

What arrives

{
  "id": "evt_…",
  "type": "visibility_drop",
  "createdAt": "2026-10-26T09:00:00.000Z",
  "brand": { "brandId": "prj_…", "name": "Acme" },
  "watch": { "id": "wch_…", "kind": "visibility_drop", "label": "Pricing slipping" },
  "text": "Acme's visibility on Pricing dropped: 41% of 133 answers the 7 days before, 22% of 140 in the last 7 — outside the margin of error. Next: in Recomma, call get_brief with brandId prj_….",
  "data": { "current": { "hits": 31, "sampleN": 140 }, "previous": { "hits": 55, "sampleN": 133 } }
}

text is written to be handed to an agent as its prompt. That is also what a Claude Code routine’s /fire endpoint expects, so a watch whose webhookUrl is the routine’s URL and whose webhookToken is its token wakes the routine directly, with your connectors, to act on the change. n8n, Zapier and your own receivers take the same body.

Verifying a delivery

Every delivery carries x-recomma-signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of <t>.<raw body> under the watch’s signing secret. The secret is returned once, when the watch is made.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret: string, body: string, header: string | null) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
  if (!match) return false;
  const [, t, v1] = match;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest();
  const given = Buffer.from(v1, "hex");
  return expected.length === given.length && timingSafeEqual(expected, given);
}

A receiver that does not answer 2xx is tried again after a minute, five minutes, half an hour, two hours and twelve hours, then given up on. x-recomma-delivery is the same on every retry, so a receiver can ignore one it has already handled. send_test_event sends one now and returns the status the receiver gave.

Webhook addresses must be https, and Recomma will not call an address that resolves to a private or local network.

Settings → Connect AI → Watches lists every watch your agents made, where it sends and whether deliveries are landing, and lets you send a test or delete one.

Hand over: fix packets

Recomma cannot change your site; the agent in your repository can. get_fix_packet turns a ticket into work that agent can carry out:

• who it is for — a coding agent for an audit rule, a content writer for a page of your own, outreach for a site to get onto;
• the tasks, each with the pages it applies to and the markup as it is and as it should be — one task per distinct change, with its pages listed;
• what it is measured by — the questions it should move, with how often they name you now;
• when it is done — the calls that prove it, in order.

Check: check_page

After a fix ships, check_page reads that page of your site now and runs the audit rules on it. It says which rules the last crawl recorded that the page no longer breaks, which it still breaks, and anything new — with the markup to change. It takes seconds, costs nothing, reads only your own domains and their subdomains, and writes nothing: the scheduled crawl stays the record.

The full loop, from an agent in your repository:

1. get_fix_packet on the top audit ticket.
2. Make the change.
3. check_page on each page it lists, until the rule is under fixed.
4. set_action_status to done — Recomma freezes today’s reading.
5. create_watch with kind action_verified to hear whether the questions moved.

Report: get_report

Agencies report to clients, and brand teams report upwards. When a person asks their agent for the report, get_report returns it ready to send:

• any period — from and to, or neither for the last full calendar month — against the same length before it;
• the summary, visibility with its sample and whether it moved, share of voice, position and sentiment;
• the daily trend against the leading competitors, the competitor table and each AI engine;
• the questions gaining and losing ground, the sites cited most and newly;
• the work finished in the period and what it moved, and what to do next.

Every figure, table and chart is rendered by Recomma from the same readings as the dashboard. What the agent adds is words: a commentary with a summary, highlights and recommendations, rendered as text. branding makes it the sender’s — preparedBy, an accent colour, a logo, and poweredBy: false to leave Recomma out entirely. It comes as Markdown, as one self-contained HTML page with no scripts, or as the figures in JSON, in English or Chinese, and over REST at /v1/agent/report.

Recomma does not send it anywhere. The agent saves or sends it through whatever the team already uses — a client portal, a shared drive, an email — and a person reviews it first. Each recommendation carries a stable data-row id, so a review tool can collect the client’s answer per row, and the agent can act on the approvals with the write tools.

For agents that find you on their own

• https://api.recomma.ai/skills/recomma-geo/SKILL.md is an Agent Skill: save it into an agent’s skills folder and the agent picks Recomma by itself when a question is about AI visibility. It is listed at https://api.recomma.ai/.well-known/skills/index.json.
• https://recomma.ai/llms.txt points an agent at the server, the skill, the REST reference and these docs.