Docs · REST API
REST API
Authentication, the response envelope, agent-actionable errors, endpoints, and signed webhooks for the LLMentions REST API.
↓ Markdown for agents- Base URL:
https://api.llmentions.com - Spec:
/openapi.json(OpenAPI 3.1) - Auth:
Authorization: Bearer sk_…(or anx-api-keyheader). Sign in to get a key. - Idempotency: send
Idempotency-Keyon cost-bearingPOSTs to make retries safe.
Envelope
Every response looks like this:
{
"data": { },
"meta": { "charged_usd": 0.15, "balance_usd": 4.85, "cached": false, "truncated": false }
}charged_usd is what the call cost. It is 0 for reads of stored data, for dry runs, and for test keys.
Errors
Errors use real HTTP status codes and always tell you what to do next:
{ "error": { "type": "budget_exceeded",
"message": "insufficient balance: this run costs $1.2000, balance is $0.4000",
"hint": "lower `samples` or prompts, use a test key (free mock engines), or top up the balance" } }| Status | type |
|---|---|
| 400 | invalid_request |
| 401 | auth |
| 402 | budget_exceeded |
| 403 | forbidden |
| 404 | not_found |
| 429 | rate_limited (with retry_after) |
| 502 | upstream |
Endpoints
| Method and path | Purpose | Cost |
|---|---|---|
GET /v1/account |
Workspace, mode, balance, engines, webhook_secret |
free |
GET /v1/engines · GET /v1/prices |
Engines and the price list. No auth | free |
POST /v1/ai/answers |
Ask engines now (synchronous) | per answer |
GET/POST /v1/projects |
List or create projects | free |
POST /v1/projects/{p}/prompts |
{add, remove} tracked prompts |
free |
POST /v1/visibility/runs |
Start a panel. Returns 202 with Location: /v1/jobs/{id} |
per answer |
GET /v1/jobs/{id} |
Job status, progress, charge, report | free |
GET /v1/projects/{p}/visibility |
Latest report (?all_runs=true pools every run) |
free |
GET /v1/projects/{p}/answers |
Stored answers (engine, brand, missing_target, q, limit) |
free |
POST /v1/projects/{p}/analyze |
{all_runs?, force?, dry_run?} labels answers with the analysis squad and returns perception rates per brand |
$0.002 / answer |
POST /v1/site/audit |
{url, max_pages?, render?, bot_view?, background?, dry_run?} crawls as AI bots see the site; returns {audit_id, audit: {status, report}, changes}. Above 25 pages it runs in the background |
$0.0002 / page crawled, $0.002 / page rendered |
GET /v1/site/audits/{audit} |
A stored audit by id, or a domain's latest, with changes since the previous audit |
free |
POST /v1/bots/report |
{log} raw server log (≤ 20 MB) returns hits, status codes, top paths and IP verification (verified / spoofed / unverifiable) per bot |
free |
POST /v1/prompts/suggest |
{category, brand? or project?, competitors?, audience?, n?, locale?, track?} returns buyer questions by intent |
$0.02 / call |
GET/POST /v1/keys · DELETE /v1/keys/{id} |
Manage keys | free |
GET /v1/bots/lookup?ua=… |
Identify an AI or search crawler from its User-Agent | free |
{p} takes a project id, its name or its domain. Names are case-insensitive.
POST /v1/ai/answers
| Field | Type | Notes |
|---|---|---|
prompts |
string[] | required |
engines |
string[] | chatgpt, chatgpt_ui, google_ai_mode, gemini, claude, perplexity, grok, deepseek, qwen, kimi (experimental). Omit for all configured engines |
samples |
int | 1–10, default 1. Prompts × engines × samples ≤ 50 |
locale |
string | BCP-47, default en-US |
web_search |
bool | false runs a parametric probe: what the model "knows" without searching |
brand, brand_aliases, domain, competitors |
optional. Adds mention detection, citation classes and a report |
|
dry_run |
bool | returns the quote only |
Each item in answers has these fields:
engine,source,model_version,prompt,textmentions[] {brand, is_target, position, count}citations[] {url, domain, title, position, class}search_queries[],latency_ms,refused
POST /v1/visibility/runs
{project, prompts?, engines?, samples (1–50, default 5), locale?, web_search?, queued?, webhook_url?, dry_run?}
- Quote first.
dry_run: truereturns{checks, price_usd, engines, missing}. - Billing. A real run holds the quoted price up front. When it finishes, only successful answers are charged and the rest is refunded.
queued: trueuses the standard queue for consumer-UI engines (chatgpt_ui,google_ai_mode). It costs $0.003 instead of $0.01 per answer, and results take minutes instead of seconds.
Webhooks
Pass webhook_url, a public https:// URL, and we POST the finished job to it:
POST /your/hook
Content-Type: application/json
LLMentions-Signature: t=1795219200,v1=5f1c…
{"type":"job.finished","job":{"id":"…","status":"succeeded","charged_usd":0.6,"report":{…}}}To verify a delivery, compute HMAC-SHA256 over "<t>.<raw body>" with your workspace's webhook_secret (from GET /v1/account), compare it in constant time, and reject a t older than 5 minutes.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const want = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return timingSafeEqual(Buffer.from(want), Buffer.from(v1));
}import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
want = hmac.new(secret.encode(), f'{parts["t"]}.'.encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(want, parts["v1"])Delivery details:
- We make up to 3 attempts, at 0 s, 5 s and 30 s.
- Redirects are not followed.
- Private and link-local addresses are refused.
- If delivery fails, it is noted in the job's
errors, soGET /v1/jobs/{id}stays the source of truth.