API Reference

14 REST endpoints for submitting audits, polling status, retrieving results, and accessing visibility reports.

Base URL

All endpoints are prefixed with this base URL.

bash

https:"code-comment">//audit.aeocontent.ai/api/v1

Authentication

All requests require a Bearer token in the Authorization header.

bash

Authorization: Bearer aeo_live_...

See Authentication for details on creating keys, permissions, and rate limits.

Response Format

All successful responses return a data object and a meta object with a unique request ID and timestamp.

Success response

json

{
  class="code-string">"data": { ... },
  class="code-string">"meta": {
    class="code-string">"request_id": class="code-string">"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    class="code-string">"timestamp": class="code-string">"2026-02-22T12:00:00.000Z"
  }
}

Paginated responses include page, per_page, and total in the meta object.

Paginated response

json

{
  class="code-string">"data": [ ... ],
  class="code-string">"meta": {
    class="code-string">"request_id": class="code-string">"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    class="code-string">"timestamp": class="code-string">"2026-02-22T12:00:00.000Z",
    class="code-string">"page": 1,
    class="code-string">"per_page": 20,
    class="code-string">"total": 47
  }
}

Error responses return an error object with a machine-readable code and a human-readable message.

Error response

json

{
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"error_code",
    class="code-string">"message": class="code-string">"Human-readable message"
  }
}

Error Codes

Code	Status	Description
`bad_request`	400	Invalid parameters or malformed request body
`unauthorized`	401	Missing or invalid API key
`forbidden`	403	API key lacks the required permission for this endpoint
`not_found`	404	The requested resource does not exist
`rate_limited`	429	Per-key rate limit exceeded - retry after the reset window
`internal_error`	500	Unexpected server error - contact support if persistent

Endpoints

Method	Path	Description	Permission
GET	`/audits/[slug]/discovery`	Fetch discovery findings	`read`
GET	`/audits/[slug]/opportunities`	Get prioritized opportunities and fixes	`read`
POST	`/audits/[slug]/reaudit`	Request fresh re-audit	`read`
GET	`/audits/[slug]`	Get full audit details	`read`
GET	`/audits/[slug]/status`	Check audit job status	`read`
POST	`/audits`	Submit a domain for audit	`write`
GET	`/audits`	List your audits	`read`
GET	`/openapi.json`	OpenAPI 3.0.3 specification document	`read`
POST	`/plugin/heartbeat`	WordPress plugin heartbeat	`write`
POST	`/plugin/onboard`	Kick off first-run Discovery + Site Audit for a newly connected WordPress site	`write`
POST	`/plugin/register`	Register a WordPress site as a CMS connection	`write`
GET	`/score/[slug]`	Get cached AEO Site Rank for a domain	`read`
POST	`/toolbar/check`	Queue an instant audit from AEORank extension	`write`
POST	`/toolbar/sync`	Sync a locally-run audit from AEORank extension	`write`