API Reference

Toolbar Check

Queue an instant audit from the AEORank Chrome extension. Rate-limited by auth tier.

POST/api/v1/toolbar/check

Queue an instant audit from the AEORank Chrome extension. Supports three-tier authentication: API key (unlimited), registered JWT (1/hour), or anonymous install ID (5 free audits).

Code Examples

curl (API key):

bash

curl -X POST "https:">//www.aeocontent.ai/api/v1/toolbar/check" \
  -H "Authorization: Bearer $AEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

curl (anonymous install):

bash

curl -X POST "https:">//www.aeocontent.ai/api/v1/toolbar/check" \
  -H "X-Install-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

Try it

Response

A new audit job has been queued. Use the poll_url to check progress.

201Audit queued

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"score": 72,
    class="code-string">"verdict": class="code-string">"Good AEO readiness with room for improvement.",
    class="code-string">"engines": { class="code-string">"instant": 72 },
    class="code-string">"last_audit": class="code-string">"2026-03-15T10:30:00.000Z"
  },
  class="code-string">"job": { class="code-string">"id": class="code-string">"a1b2c3d4-e5f6-7890-abcd-ef1234567890", class="code-string">"status": class="code-string">"pending" },
  class="code-string">"poll_url": class="code-string">"/api/job-status?slug=example-com&engine=instant",
  class="code-string">"tier": class="code-string">"anonymous",
  class="code-string">"free_audits_remaining": 4
}

When an anonymous user has exhausted their 5 free audits, returns the cached score with an upgrade prompt.

200Cached score (free audits exhausted)

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"score": 72,
    class="code-string">"verdict": class="code-string">"Good AEO readiness with room for improvement.",
    class="code-string">"engines": { class="code-string">"instant": 72 },
    class="code-string">"last_audit": class="code-string">"2026-03-15T10:30:00.000Z"
  },
  class="code-string">"tier": class="code-string">"anonymous",
  class="code-string">"free_audits_remaining": 0,
  class="code-string">"upgrade": true,
  class="code-string">"upgrade_url": class="code-string">"https:class="code-commentclass="code-string">">//www.aeocontent.ai/pricing",
  class="code-string">"message": class="code-string">"Free audits used. Sign in for hourly checks or get an API key for unlimited."
}

401No auth provided

json

{
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"unauthorized",
    class="code-string">"message": class="code-string">"Provide an API key, auth token, or X-Install-Id header."
  }
}

Three auth tiers: Authorization: Bearer <key> for unlimited audits, X-Auth-Token for registered users (1/hour), or X-Install-Id for anonymous installs (5 free audits).

Code Examples

curl (API key):

bash

curl -X POST "https:">//www.aeocontent.ai/api/v1/toolbar/check" \
  -H "Authorization: Bearer $AEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

curl (anonymous install):

bash

curl -X POST "https:">//www.aeocontent.ai/api/v1/toolbar/check" \
  -H "X-Install-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

Response

A new audit job has been queued. Use the poll_url to check progress.

201Audit queued

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"score": 72,
    class="code-string">"verdict": class="code-string">"Good AEO readiness with room for improvement.",
    class="code-string">"engines": { class="code-string">"instant": 72 },
    class="code-string">"last_audit": class="code-string">"2026-03-15T10:30:00.000Z"
  },
  class="code-string">"job": { class="code-string">"id": class="code-string">"a1b2c3d4-e5f6-7890-abcd-ef1234567890", class="code-string">"status": class="code-string">"pending" },
  class="code-string">"poll_url": class="code-string">"/api/job-status?slug=example-com&engine=instant",
  class="code-string">"tier": class="code-string">"anonymous",
  class="code-string">"free_audits_remaining": 4
}

When an anonymous user has exhausted their 5 free audits, returns the cached score with an upgrade prompt.

200Cached score (free audits exhausted)

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"score": 72,
    class="code-string">"verdict": class="code-string">"Good AEO readiness with room for improvement.",
    class="code-string">"engines": { class="code-string">"instant": 72 },
    class="code-string">"last_audit": class="code-string">"2026-03-15T10:30:00.000Z"
  },
  class="code-string">"tier": class="code-string">"anonymous",
  class="code-string">"free_audits_remaining": 0,
  class="code-string">"upgrade": true,
  class="code-string">"upgrade_url": class="code-string">"https:class="code-commentclass="code-string">">//www.aeocontent.ai/pricing",
  class="code-string">"message": class="code-string">"Free audits used. Sign in for hourly checks or get an API key for unlimited."
}

401No auth provided

json

{
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"unauthorized",
    class="code-string">"message": class="code-string">"Provide an API key, auth token, or X-Install-Id header."
  }
}