# AEO Spotlight API — Full Reference (llms-full.txt)

> AEO Spotlight is the brand-truth layer for AI visibility. This file is the expanded agent
> reference. Read `llms.txt` for the index; this file adds endpoint detail, the async job
> contract, webhook events, error codes, and the Agent Control (permissioned autonomy) model.

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

## Auth & keys
- Header `X-API-Key: aeo_live_...`. Keys are created in the dashboard (Developer → API Keys),
  are hash-stored, and carry scopes. Publish implies read_write.
- `GET /api/v1/me` returns scopes, credits_balance, spent_today, daily_credit_ceiling,
  rpm_limit, autonomy_level (L0/L1/L2), pending_approvals, and a deterministic capabilities list.
- Anonymous free funnel: `POST /api/v1/brand-check` (reCAPTCHA + 3/day rate limit).

## Read endpoints
- `GET /api/v1/queries` — monitoring queries for the tenant.
- `GET /api/v1/citations?platform=&sentiment=&sourceType=&hasMention=&dateFrom=&dateTo=&page=&pageSize=`
  — brand citations. sourceType: ai_response | organic_search | info_site.
- `GET /api/v1/gaps?status=` — 4-tier visibility gaps (no_mention / weak_mention /
  competitor_dominated / low_visibility) as content opportunities.
- `GET /api/v1/opportunities/{id}` — opportunity + brief + content + publish status.
- `GET /api/v1/competitors` — tracked competitors.
- `GET /api/v1/competitors/{id}` — single competitor.
- `GET /api/v1/jobs` and `GET /api/v1/jobs/{id}` — async job list/status.
- `GET /api/v1/webhooks` — webhook subscriptions.

## Write endpoints (async, idempotent)
- `POST /api/v1/queries/{id}/run` — run a monitoring query across AI platforms (credit-metered).
- `POST /api/v1/gaps/detect` — trigger 4-tier detection. body: { brandProfileId }.
- `POST /api/v1/opportunities/{id}/generate-brief` — body: { contentFormat }.
- `POST /api/v1/opportunities/{id}/generate-content` — body: { persona }.
- `POST /api/v1/opportunities/{id}/publish` — body: { destinationId, mode }.
  mode "propose" creates an approval request (Agent Control); mode "execute" publishes only at
  L2 autonomy or with an approved request for that opportunity.
- All writes return `202` + jobId; send `Idempotency-Key` to retry safely (a retry returns the
  original job, never double-runs).

## Async job contract
- Status: queued → running → succeeded | partial | failed.
- `perPlatformStatus` records per-provider partial success — never all-or-nothing.
- Failed executions deduct 0 credits; `Retry-After` is returned on 429/402.

## Webhooks
- Manage via `POST/GET/PUT/DELETE /api/v1/webhooks` + `POST /api/v1/webhooks/{id}/ping`.
- Events: execution.started/completed/failed, mention.detected, visibility.dropped,
  gap.detected, competitor.entered, opportunity.created, content.brief_generated,
  content.generated, content.published, content.cited, credit.low, credit.ceiling_reached,
  api_key.revoked, webhook.ping.
- Delivery: `POST` JSON, `X-AeoSpotlight-Signature: sha256=<hex>` (HMAC-SHA256), retries with
  backoff (max 5), dead-lettered after exhaustion. Consumers dedupe on `event_id`.

## Agent Control (permissioned autonomy)
- Agents are scoped keys flagged `isAgent`. Trust-earned levels:
  L0 manual (all side-effects require approval) → L1 auto-propose (≥3 approved) →
  L2 auto-publish (≥20 approved with ≥95% approval rate).
- Every action is audit-logged (agent_actions) incl. the exact LLM prompt (forensics).
- Human review: `GET /api/tracker/approvals/pending`, `POST /api/tracker/approvals/{id}/approve|reject`.

## Errors
- Envelope: `{ "error": { "code", "message", "details" } }`.
- Codes: missing_api_key/invalid_api_key (401), insufficient_scope (403),
  approval_required (403), not_found (404), idempotency_conflict (409),
  approval_pending (409), validation_error (422), rate_limit_exceeded /
  credit_ceiling_reached (429), insufficient_credits (402).

Full machine-readable spec: `GET /openapi.json`.