Docs / Developers / Public API

Public API quickstart

AEO Spotlight is a REST API. Pull verdict-aware citations, 4-tier visibility gaps, competitor snapshots, and the content lifecycle as JSON — then react to it with signed webhooks. Everything under /api/v1, async by design, one credit ledger.

For developersFor agencies & automationBase URL: api.aeospotlight.com

1 · Get an API key

Open the dashboard → Developer → API Keys → New key.

Choose your scopes (see below).

Copy the key — it starts with aeo_live_… and is shown exactly once. It is stored hashed on our side; if you lose it, revoke and create a new one.

Scoped, revocable, budgeted Keys are multi-per-key: each can carry its own scopes, rate limits, and a daily credit ceiling so a misbehaving script or agent can't drain your balance. Revoke any key instantly.

2 · Base URL & authentication

All endpoints live under the versioned base path. Authenticate every request with an X-API-Key header:

BASE = https://api.aeospotlight.com/api/v1

# every request:
curl $BASE/me \
  -H "X-API-Key: aeo_live_YOUR_KEY"

Scopes

Scope	Lets you…	Examples
`read`	Read visibility data.	`GET /me`, `GET /citations`, `GET /gaps`, `GET /queries`, `GET /competitors`, `GET /jobs`, list webhooks
`read_write`	Everything in `read`, plus writes and executions.	`POST /queries/{id}/run`, `POST /gaps/detect`, generate brief/content, manage webhooks
`publish`	Highest privilege — publishing content.	`POST /opportunities/{id}/publish` (implies `read_write`)

Publishing is its own scope on purpose. The highest-risk action never rides along with a generic write key. Depending on your autonomy level, a publish may first be proposed for human approval.

3 · Quick calls

Check your entitlements

GET /meshell

curl https://api.aeospotlight.com/api/v1/me \
  -H "X-API-Key: aeo_live_YOUR_KEY"

Returns your tenant, credit balance, scopes, rate limits, and capabilities — the deterministic entitlements your client should read on startup.

List visibility gaps

GET /gapsshell

curl "https://api.aeospotlight.com/api/v1/gaps?status=open" \
  -H "X-API-Key: aeo_live_YOUR_KEY"

Returns the tenant's 4-tier visibility gaps (no-mention, weak-mention, competitor-dominated, low-visibility) and their lifecycle status.

Run a monitoring query (async)

POST /queries/{id}/runshell

curl -X POST https://api.aeospotlight.com/api/v1/queries/42/run \
  -H "X-API-Key: aeo_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-request-1"

AI providers take 10–60s+, so executions run asynchronously. You get:

HTTP/1.1 202 Accepted
{ "jobId": "job_abc123", "status": "queued" }

Poll the job

GET /jobs/{jobId}shell

curl https://api.aeospotlight.com/api/v1/jobs/job_abc123 \
  -H "X-API-Key: aeo_live_YOUR_KEY"

When finished: status: succeeded with perPlatformStatus[] — per-provider detectionVerdict + evidence. Failed runs are free — credits are only charged on success/partial success.

4 · Async jobs & idempotency

Async-by-design: paid executions (run query, gaps/detect, generate brief/content) return 202 + a jobId. Poll GET /jobs/{id} or wait for the completion webhook event.
Idempotency keys: send an Idempotency-Key header on every write. If you retry (network blip, agent retry loop), the platform can dedupe — no double-runs, no double credit burn.
Per-provider partial results: a multi-platform run can report per-platform status; one platform failing doesn't fail the whole job.
Charge on success only. One shared credit ledger across your keys.

5 · Webhook subscriptions (push events)

Don't poll — subscribe to an HTTPS endpoint and receive signed events the moment they happen. See the API reference for the full event catalog.

Subscribeshell

curl -X POST https://api.aeospotlight.com/api/v1/webhooks \
  -H "X-API-Key: aeo_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://yourapp.example.com/aeo-events", "events": ["content.published", "content.cited", "mention.detected"] }'

The response includes your subscription plus the HMAC secret exactly once — use it to verify signatures on every delivery.
Delivery: POST JSON with X-AeoSpotlight-Signature: sha256=[hex] (HMAC-SHA256 of the raw body) and User-Agent: AeoSpotlight-Webhooks/1.0. Endpoints must be public HTTPS hosts (SSRF-guarded).
Reliability: retries with backoff (5s → 10s → 30s → 60s → 120s), max 5 attempts, then dead-lettered. Retries keep the same event_id, so dedupe on it.
Test a subscription with POST /api/v1/webhooks/{id}/ping.

Content delivery ≠ event webhooks Webhook subscriptions deliver small event notifications. To receive the full published article, configure a publish destination — see Receive content via webhook.

6 · Errors & limits

Standard error envelope: errors come back as { "error": { "code", "message", "details" } } with an appropriate HTTP status (e.g. 401 missing_api_key, 403 insufficient_scope).
Rate limits are enforced per API key; hitting one returns 429. Read your limits from GET /me.
Credits & ceilings: executions deduct credits on success/partial only, capped per key per day if you set a ceiling.

7 · Full reference & tooling

OpenAPI spec — the complete, machine-readable contract (interactive UI at /swagger).
llms.txt + llms-full.txt — agent-native indexes.
Postman collection — import and go.
The detection-verdict trust layer: every citation returns why the system knows (GroundedCitation / ExactCleanMatch / AmbiguousOnly / NotDetected + evidence) — not raw rows.

Previous← Connect Google Search Console NextDocumentation home →