API Reference

Submit Audit

Submit a domain for AEO audit and receive a job reference for status polling.

POST/api/v1/audits

Submit a domain for AEO audit. Returns immediately with a job reference.

Request Body

Name	Type	Required	Description
`domain`	string	Required	The domain to audit (e.g., "example.com"). Protocol and www prefix are stripped automatically.

Example

bash

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

Response

On success, the API returns the audit slug and current status. Use the slug to GET /audits/[slug]/status and poll until the audit reaches completed.

200Audit queued

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"domain": class="code-string">"example.com",
    class="code-string">"status": class="code-string">"pending",
    class="code-string">"message": class="code-string">"Audit queued"
  },
  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"
  }
}

Duplicate Handling

If the domain was recently audited (within 7 days), the API returns the existing audit immediately instead of queuing a new one.

200Existing audit returned

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"domain": class="code-string">"example.com",
    class="code-string">"status": class="code-string">"completed",
    class="code-string">"message": class="code-string">"Audit already exists",
    class="code-string">"score": 72
  },
  class="code-string">"meta": {
    class="code-string">"request_id": class="code-string">"b2c3d4e5-f6a7-8901-bcde-f12345678901",
    class="code-string">"timestamp": class="code-string">"2026-02-22T12:05:00.000Z"
  }
}

Errors

400Invalid domain

json

{
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"bad_request",
    class="code-string">"message": class="code-string">"Invalid domain format"
  }
}

Domain normalization strips the protocol (http/https), www prefix, and trailing paths. https://www.example.com/about becomes example.com.

Name

Type

Required

Description

domain

string

Required

The domain to audit (e.g., "example.com"). Protocol and www prefix are stripped automatically.

Example

bash

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

Response

On success, the API returns the audit slug and current status. Use the slug to GET /audits/[slug]/status and poll until the audit reaches completed.

200Audit queued

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"domain": class="code-string">"example.com",
    class="code-string">"status": class="code-string">"pending",
    class="code-string">"message": class="code-string">"Audit queued"
  },
  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"
  }
}

Duplicate Handling

If the domain was recently audited (within 7 days), the API returns the existing audit immediately instead of queuing a new one.

200Existing audit returned

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"domain": class="code-string">"example.com",
    class="code-string">"status": class="code-string">"completed",
    class="code-string">"message": class="code-string">"Audit already exists",
    class="code-string">"score": 72
  },
  class="code-string">"meta": {
    class="code-string">"request_id": class="code-string">"b2c3d4e5-f6a7-8901-bcde-f12345678901",
    class="code-string">"timestamp": class="code-string">"2026-02-22T12:05:00.000Z"
  }
}

Errors

400Invalid domain

json

{
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"bad_request",
    class="code-string">"message": class="code-string">"Invalid domain format"
  }
}

Domain normalization strips the protocol (http/https), www prefix, and trailing paths. https://www.example.com/about becomes example.com.