LLMentions

REST API

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
POST /v1/signup Create a workspace and a test key. No auth free
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:

POST /v1/visibility/runs

{project, prompts?, engines?, samples (1–50, default 5), locale?, web_search?, queued?, webhook_url?, dry_run?}

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: