---
title: REST API
description: Authentication, the response envelope, agent-actionable errors, endpoints, and signed webhooks for the LLMentions REST API.
group: Interfaces
---

# REST API

- **Base URL:** `https://api.llmentions.com`
- **Spec:** [`/openapi.json`](https://api.llmentions.com/openapi.json) (OpenAPI 3.1)
- **Auth:** `Authorization: Bearer sk_…` (or an `x-api-key` header). [Sign in](https://api.llmentions.com/login) to get a key.
- **Idempotency:** send `Idempotency-Key` on cost-bearing `POST`s to make retries safe.

## Envelope

Every response looks like this:

```json
{
  "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:

```json
{ "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`, `text`
- `mentions[] {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: true` returns `{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: true`** uses 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.

```js
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));
}
```

```python
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`, so `GET /v1/jobs/{id}` stays the source of truth.
