02 · Quickstart

Get the AEO badge for any domain

The fastest 'hello world' — fetch the AEO badge SVG for any public-audited domain.

curl https://seochatai.com/api/badge/example.com

No auth header. No API key. Just call. The response is a self-contained SVG you can drop into an <img> tag or save to disk.

03 · Rate limits

Limits and conventions

· 60 requests per minute per IP across all public endpoints.
· All endpoints are GET, JSON responses (except /api/badge which returns SVG).
· All endpoints set permissive CORS (Access-Control-Allow-Origin: *).
· All endpoints respect the same PRIVATE-audit filter — privacy non-negotiable.
· Errors return JSON: { error: string, code?: string } with appropriate HTTP status.

04 · Endpoints

Endpoint reference

GET/api/badge/[domain]

AEO Visibility Badge SVG

Returns an embeddable SVG badge showing the AEO/GEO Visibility grade + score for a domain's most recent PUBLIC + COMPLETED audit. Returns a neutral fallback badge for unknown domains or PRIVATE audits.

Query params

size: default (320×80) | square (100×100) | compact (200×60)

Example

GET /api/badge/example.com?size=square

Response

image/svg+xml — fully self-contained SVG with inline styles + tracking pixel

Cache-Control

public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800

GET/api/scan/[domain]

Public audit summary by domain

Returns sanitized audit data for the most recent PUBLIC + COMPLETED audit of a domain. Includes overall + category scores, top check failures, and metadata. Code-level fixes are stripped (those require a free account).

Example

GET /api/scan/example.com

Response

application/json — { domain, overallScore, categoryScores, topIssues, auditedAt, publicUrl }

Cache-Control

public, max-age=300, s-maxage=600

GET/api/audit/public

Public audit gallery list (paginated)

Returns a cursor-paginated list of all PUBLIC + COMPLETED audits. Use the cursor from the previous response to fetch the next page. Useful for building dashboards or competitive monitoring tools on top of the corpus.

Query params

cursor: Audit ID returned from the previous response's nextCursor field
limit: Page size, 1-100, default 25

Example

GET /api/audit/public?limit=25

Response

application/json — { items: Audit[], nextCursor: string | null }

Cache-Control

public, max-age=60, s-maxage=300

GET/api/audit/[id]/badge-stats

Badge impression statistics

Returns BadgeImpression aggregate for an audit's domain — total impressions, last-7-day count, unique embedder hosts. Mirrors the badge SVG's privacy model: 404 for PRIVATE / non-COMPLETED audits.

Example

GET /api/audit/abc123/badge-stats

Response

application/json — { domain, totalImpressions, trueImpressions, cacheMissImpressions, uniqueEmbedders, last7Days, firstSeen, lastSeen }

Cache-Control

public, max-age=60, s-maxage=300, stale-while-revalidate=900

05 · Use cases

What people build with these APIs

Embed badges — drop the AEO badge SVG into customer dashboards or marketing sites with one <img> tag.
Competitive monitoring — poll /api/scan/[domain] for competitors weekly and chart score deltas in your BI tool.
Build your own gallery — paginate /api/audit/public and surface industry-specific subsets on your own site.
Impression reports — fetch /api/audit/[id]/badge-stats for the badges you embedded and show real impression counts to your customers.

06 · Related

AEO Leaderboard

Browse the corpus visually before building on it.

What is AEO?

Background on the audit signals exposed via API.

Last updated · 2026-07-15