Run AI visibility checks from your agent.
For developersUpdated October 2026API v1
Ask your coding agent “is my product recommended by ChatGPT for meeting scheduling?” and have it find out. An API key from your account lets an agent, a script or the recomention MCP server start a report, wait for it, and read every number and answer in it.
API keys.
- Shown once. When you create a key we show it one time. We store a fingerprint of it, not the key, so nobody here can show it to you again. Lost one? Revoke it and make another.
- Send it as a Bearer token:
Authorization: Bearer <key>. Keep it out of repositories; put it in your agent’s environment. - One key per agent or machine, so you can revoke one without breaking the others. Each key has its own rate limit.
- A key reads only its own account. Another account’s report answers the same as a report that doesn’t exist.
The JSON API.
Starting a report is never free and never guessed: the body names its funding, and nothing runs without it. funding: “credits” spends one agency credit on a Full report, exactly as agency credits work from your account.
curl -X POST https://www.recomention.com/api/v1/reports \
-H "Authorization: Bearer $RECOMENTION_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "domain": "example.com", "category": "meeting scheduling", "description": "Booking links for sales teams", "plan": "FULL", "funding": "credits" }'Optional fields: brand, engines (a subset of the plan’s), seedPrompts (questions you want asked; we write the rest, and none may name the product), and idempotencyKey, so a retried request lands on the same report instead of starting a second one.
A report takes several minutes. Poll its status about once a minute. When it is complete, the report JSON has the score, each engine’s “named in n of m answers”, who was named instead, the sources, the fix list and every answer. An engine that could not run is listed under enginesSkipped with the reason; it is never counted as an engine that left you out.
The MCP server.
The recomention MCP server is on its way to npm. Until it is listed, everything it does is available through the JSON API above, with the same key.
recomention_rankings_list— List the public AI rankings.recomention_rankings_get— One ranking: who the engines name for a category, with counts.recomention_suggest_prompts— Buyer questions worth checking, from templates. No model call, no cost.recomention_report_start— Start a report, funded by an agency credit or by your own provider keys.recomention_report_status— Where a report is: queued, running, finished or failed.recomention_report_get— A finished report as JSON: scores, competitors, sources, fix list, every answer.recomention_distribution_kit— A finished report as Markdown files for your agent: where to get mentioned and a channel plan.recomention_reports_list— Your reports, newest first.
The distribution kit.
A finished report becomes a set of Markdown files your agent reads before it acts: what the product is and the buyer questions, who the engines name instead, the measured result per engine, the third-party pages, subreddits and videos the engines cite for a rival and not for you, and a channel plan ranked by those citations, each channel with a first task. Get it with recomention_distribution_kit, from /api/v1/reports/:slug/kit, or as a .zip from the project dashboard. It is built from the report’s own data, with no extra model call. Every count keeps its denominator, and nothing in it promises traffic: a later report shows whether the answers moved.
Bring your own keys.
Bring Your Own Key is built and switched off on this server for now. Here is exactly how it treats your keys, so you can decide before it opens.
- Used for that one report, then gone. Your keys are held in memory while the report runs. They are never written to our database or our logs.
- Locked while queued. The job waiting in the queue carries your keys encrypted. The other half of the lock is destroyed when the report ends, and it expires after a day regardless, so the queued copy can never be read again.
- Only your keys. Every model call in a BYOK report uses the keys you sent, or a method that calls no model at all. We never fall back to ours.
- A rejected key is stated, not scored. If a provider refuses your key, that engine shows as skipped with the reason “provider rejected the key”. It never counts as an engine that didn’t name you.
- What we keep: that the report was BYOK, and which engines you sent a key for.
Pricing.
Through the API a report on our keys is paid with an agency credit: one credit, one Full report on ChatGPT, Claude, Perplexity, Gemini, Grok and AI Overview.