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:">//www.aeocontent.ai/api/v1/audits" \
  -H "Authorization: Bearer $AEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

Try it

Response

On success the API queues a new audit and returns 201 Created. Use the slug to poll GET /audits/[slug]/status until the audit reaches completed.

201New audit 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">"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"
  }
}

If the domain has been audited before, returns 200 with the existing engines array instead of queuing a new job.

200Existing audit found

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">"engines": [
      {
        class="code-string">"engine": class="code-string">"chatgpt",
        class="code-string">"overall_score": 72
      }
    ]
  },
  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"
  }
}

If a job is already queued or in progress for this domain, returns 200 with the current stage.

200Job already in queue

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">"queued",
    class="code-string">"current_stage": class="code-string">"discovering"
  },
  class="code-string">"meta": {
    class="code-string">"request_id": class="code-string">"c3d4e5f6-a7b8-9012-cdef-123456789012",
    class="code-string">"timestamp": class="code-string">"2026-02-22T12:01:00.000Z"
  }
}

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:">//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 queues a new audit and returns 201 Created. Use the slug to poll GET /audits/[slug]/status until the audit reaches completed.

201New audit 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">"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"
  }
}

If the domain has been audited before, returns 200 with the existing engines array instead of queuing a new job.

200Existing audit found

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">"engines": [
      {
        class="code-string">"engine": class="code-string">"chatgpt",
        class="code-string">"overall_score": 72
      }
    ]
  },
  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"
  }
}

If a job is already queued or in progress for this domain, returns 200 with the current stage.

200Job already in queue

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">"queued",
    class="code-string">"current_stage": class="code-string">"discovering"
  },
  class="code-string">"meta": {
    class="code-string">"request_id": class="code-string">"c3d4e5f6-a7b8-9012-cdef-123456789012",
    class="code-string">"timestamp": class="code-string">"2026-02-22T12:01:00.000Z"
  }
}

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."
  }
}