Aura AI Visibility API documentation

Version 1.0.0 · Updated 2026-09-20

The Aura API gives you two things: a free, keyless readiness scan of any domain, and — with an API key — the measurement data behind a Monitor project, including citation sampling, share of voice, competitor comparison, citation sources and AI-crawler traffic. Every sampled rate is returned with the sample size and 95% confidence interval that produced it, and is returned asnull rather than a number when the sample is too small to support one.

The machine-readable description of everything on this page is at /api/openapi.json (OpenAPI 3.1). This page is generated from that same document, so the two cannot disagree.

How do I authenticate with the Aura API?

Send your key as a bearer token. An API key is a string beginning aai_key_ that you create in Settings → API keys; it is shown once, stored only as a SHA-256 hash, scoped to specific projects and to read or read+write access, and revocable at any time.

curl 'https://www.aaivisibility.com/api/monitor/citation?domain=example.com' \
  -H 'Authorization: Bearer $AURA_API_KEY'

Access is checked per project, not per account, because a plan belongs to a subscription rather than to the account that owns it. The same key can answer 200 for one project and 403 with code: "plan_access_required" for another on the same account, if that project's plan does not include API access. Revocation is immediate: the request after you revoke a key returns 401.

Two other credentials appear in this document and are not API keys. The project ingest token (Settings → Connectors) authenticates POST /api/track only; it can write log events and read nothing, so it is safe to put in a log pipeline. The operator token is ours, used by our cron jobs for the write operations that spend AI-provider budget. GET /api/monitor/prompts is operator-only and is therefore not part of this API.

What are the rate limits?

A rate limit is the number of requests you may make in a rolling window before the API starts refusing with 429. Aura enforces one limit per API key and a separate, smaller one per IP on the free keyless endpoints.

Rate limits. Key-authenticated requests are limited to 120 per minute per API key, in one bucket shared with the MCP endpoint — a key has one budget however it calls us. The keyless public endpoints (POST /api/scan, POST /api/generate/llms-txt) are limited to 8 requests per 5 minutes per IP, and /api/scan additionally performs at most one live crawl per domain per IP per 24 hours, serving the stored report instead of refusing. Limited responses are 429 with Retry-After in seconds. Key-authenticated responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Those counters are advisory: when the shared Redis limiter is unreachable the limiter falls back to per-instance memory for that request, so the numbers then describe one server's view of the window rather than the cluster's.

What do the numbers mean?

Every figure this API returns about AI answers is an estimate from a sample, not a fact, and the response shape says so. This section defines the terms used throughout the endpoint reference.

What the numbers mean. A mention and a citation are different measurements and are never merged: a mention is the brand named in the prose of an answer (detector mention-v2), a citation is a linkable reference to the domain. Both are estimates from a sample of non-deterministic AI answers, so both are reported as Wilson score intervals with the sample size that produced them. rate is null — never 0, never a guess — whenever n < 30 or the 95% interval half-width exceeds 15 percentage points; the reason field says which bar was missed, and n and successes are always present so you can compute your own figure. Sentiment is a lexical classifier, labelled lexical-v1 in every payload that carries it; it is not a model judgement. Agent traffic is computed from access-log events you ship to POST /api/track — AI crawlers do not execute JavaScript, so a browser beacon cannot see them and coverage equals what you send.

Mentions are not citations

A mention is your brand named in the prose of an answer, found by detector mention-v2. A citation is a linkable reference to your domain in that answer. Being talked about and being linked to are different outcomes with different fixes, so they are returned as two separate objects on every brand row and are never added together into a single visibility number.

Why rate is sometimes null

rate is null — not 0 — whenever the sample cannot support a number: fewer than 30 trials, or a 95% Wilson interval half-width wider than ±15 percentage points. When that happens, reason states which bar was missed and n and successes are still returned, so you can compute and caveat your own figure. A null rate means "not measured well enough to say", never "never happened".

Why every rate carries n and an interval

AI answers are non-deterministic and personalised, so the same prompt on the same day can produce different answers. A percentage with no sample size behind it carries almost no information: at n=7, a 43% rate has a 95% interval of roughly 18%–71%. Aura uses the Wilson score interval rather than the textbook normal interval, because the normal interval returns a zero-width interval at 0 or n successes — false certainty at exactly the sample sizes this product operates at.

Sentiment is lexical, and labelled so

Sentiment is produced by a lexical classifier and every payload carrying it also carries method: "lexical-v1". It scores the language around your brand in the sampled answer. It is not a language-model judgement, and this API does not present it as one.

Agent traffic comes from your server logs

AI crawlers do not execute JavaScript, so a browser pixel cannot observe them. Agent traffic is therefore computed only from the access-log events you ship to POST /api/track. Coverage equals what you send: the report describes your logs, and every response repeats that in its disclosure field.

What do the error responses look like?

Every non-2xx response is a JSON object with an error string. The failures this document names also carry a stable code you can branch on, so you never have to match on prose.

curl -X POST 'https://www.aaivisibility.com/api/scan' \
  -H 'Content-Type: application/json' \
  -d '{"url":"example.com"}'

curl 'https://www.aaivisibility.com/api/results/example.com'

curl -X POST 'https://www.aaivisibility.com/api/generate/llms-txt' \
  -H 'Content-Type: application/json' \
  -d '{"url":"example.com"}'

curl 'https://www.aaivisibility.com/api/monitor/history?domain=example.com' \
  -H 'Authorization: Bearer $AURA_API_KEY'

curl 'https://www.aaivisibility.com/api/monitor/citation?domain=example.com' \
  -H 'Authorization: Bearer $AURA_API_KEY'

curl 'https://www.aaivisibility.com/api/monitor/sov?domain=example.com' \
  -H 'Authorization: Bearer $AURA_API_KEY'

curl 'https://www.aaivisibility.com/api/monitor/compare?domain=example.com' \
  -H 'Authorization: Bearer $AURA_API_KEY'

curl 'https://www.aaivisibility.com/api/monitor/sources?domain=example.com' \
  -H 'Authorization: Bearer $AURA_API_KEY'

curl 'https://www.aaivisibility.com/api/monitor/agents?domain=example.com' \
  -H 'Authorization: Bearer $AURA_API_KEY'

curl -X POST 'https://www.aaivisibility.com/api/track' \
  -H 'Authorization: Bearer $AURA_INGEST_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com","events":[{"ua":"Mozilla/5.0 (compatible; GPTBot/1.0)","path":"/pricing","ts":"2026-09-20T09:00:00Z","status":200}]}'

curl 'https://www.aaivisibility.com/api/mcp'

curl -X POST 'https://www.aaivisibility.com/api/mcp' \
  -H 'Authorization: Bearer $AURA_API_KEY'

How does Aura version this API?

Versioning is the promise about what can change under you. Aura's promise is that these paths describe v1 and will not break in place.

Versioning. Paths are unversioned and describe v1. A breaking change — a field removed, a type changed, a status code repurposed — ships under a new path prefix (/api/v2/...) rather than mutating these routes. Additive changes (new fields, new optional parameters, new endpoints) happen in place and are not breaking; write clients that ignore fields they do not recognise. Deprecation. A deprecated field keeps serving for at least 90 days from the date it is marked. Every response still carrying one sends a Deprecation header (RFC 8594) with the date it was deprecated, a Sunset header with the earliest date it may be removed, and a Link header pointing at this page. Deprecated fields are marked in this document with the date. Currently deprecated: the estimate fields point and ci, deprecated 2026-09-20, serving until at least 2026-12-19 — use rate, ci_low and ci_high.

Which fields are deprecated?

A deprecated field still works. It is a field we intend to stop returning, announced in advance so you can move off it on your own schedule.

Responses that still carry these fields send a Deprecation header with the date above, a Sunset header with the earliest removal date, and a Link header pointing back to this section. The minimum notice is 90 days.

Questions

Endpoint summary

This API currently exposes 12 operations. The full machine-readable description is at /api/openapi.json.