# AEO Spotlight API

> AEO Spotlight is the brand-truth layer for AI visibility. Our public API gives you
> verified, explainable, permissioned visibility data: which AI platforms mention or cite
> your brand (DetectionVerdict + evidence), where competitors outrank you, and the content
> lifecycle from gap to AI citation. Read-first, async-by-design, one credit ledger.

## Docs
- [AEO Spotlight API — OpenAPI Specification](https://api.aeospotlight.com/openapi.json)
- [AEO Spotlight API — Full Agent Reference (llms-full.txt)](https://api.aeospotlight.com/llms-full.txt)
- [AEO Spotlight — Developers](https://aeospotlight.com/developers)

## Authentication
- Send `X-API-Key: aeo_live_...` on every request to `/api/v1/*`. Create keys in the
  dashboard under Developer → API Keys. Scopes: `read` | `read_write` | `publish`.
- Get your capabilities/limits: `GET /api/v1/me` (deterministic entitlements).

## Core resources
- `GET /api/v1/me` — entitlements, scopes, credits, autonomy level, capabilities.
- `GET /api/v1/queries` — monitoring queries (what users type into AI).
- `GET /api/v1/citations` — brand citations (platform, sentiment, relevance, source type).
- `GET /api/v1/gaps` | `/api/v1/opportunities` — 4-tier visibility gaps + content opportunities.
- `GET /api/v1/competitors` — tracked competitors.
- `GET /api/v1/jobs/{id}` — async job status.
- `GET /api/v1/webhooks` — webhook subscriptions (push events).
- `POST /api/v1/queries/{id}/run` · `/gaps/detect` · `/opportunities/{id}/generate-brief`
  · `/generate-content` · `/publish` — async writes (202 + job id).

## Async pattern
- Paid operations return `202` + `{ jobId }`. Poll `GET /api/v1/jobs/{id}` or subscribe to a
  webhook for `execution.completed`. Include `Idempotency-Key` on writes to retry safely.

## Metering
- One credit ledger. Charge on success/partial only; failed runs are free. Responses carry
  `credits_balance`; ceilings return `Retry-After`. Per-key rate limits are separate.

## Webhooks (push)
- Events: `execution.completed`, `mention.detected`, `gap.detected`, `content.published`,
  `content.cited`, `credit.ceiling_reached`, ... HMAC-SHA256 signed; idempotent via `event_id`.

## Errors
- Standard `{ "error": { "code", "message", "details" } }` envelope.

Full machine-readable reference: `GET /openapi.json` · `llms-full.txt` for details.