API Reference

Audit Discovery

Fetch the deterministic Discovery payload for an audit job. Available as soon as the discovering stage finishes — well before the rest of the pipeline completes.

GET/api/v1/audits/[slug]/discovery

Returns the full deterministic discovery payload (identity, offering, audience signals, site structure). The payload is populated the moment the discovering stage ends, so clients can render Discovery findings while auditing/seeding/visibility still run in the background.

Path Parameters

Name	Type	Required	Description
`slug`	string	Required	Domain slug (e.g., "notion-com")

Example

bash

curl "https:">//www.aeocontent.ai/api/v1/audits/example-com/discovery" \
  -H "Authorization: Bearer $AEO_API_KEY"

Try it

Response

Once the discovering stage finishes, discovery contains the full deterministic payload. The rest of the pipeline may still be running — check status/current_stage for progress.

200Discovery ready

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"status": class="code-string">"pending",
    class="code-string">"current_stage": class="code-string">"discovery complete",
    class="code-string">"discovery": null,
    class="code-string">"started_at": class="code-string">"2026-04-11T12:00:00.000Z",
    class="code-string">"completed_at": null
  },
  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"
  }
}

While the job is still in pending or early discovering, discovery is null. Poll again once current_stage advances past the discovery step.

200Discovery pending

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"status": class="code-string">"discovering",
    class="code-string">"current_stage": class="code-string">"discovering niche and competitors",
    class="code-string">"discovery": null,
    class="code-string">"started_at": class="code-string">"2026-04-11T12:00:00.000Z",
    class="code-string">"completed_at": null
  },
  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-04-11T12:00:10.000Z"
  }
}

404Not found

json

{
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"not_found",
    class="code-string">"message": class="code-string">"No audit job found for slug 'unknown-com'."
  }
}

Poll every 10–15 seconds. The deterministic discovery stage typically finishes within the first 30 seconds of a new audit.

Name

Type

Required

Description

slug

string

Required

Domain slug (e.g., "notion-com")

Example

bash

curl "https:">//www.aeocontent.ai/api/v1/audits/example-com/discovery" \
  -H "Authorization: Bearer $AEO_API_KEY"

Response

Once the discovering stage finishes, discovery contains the full deterministic payload. The rest of the pipeline may still be running — check status/current_stage for progress.

200Discovery ready

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"status": class="code-string">"pending",
    class="code-string">"current_stage": class="code-string">"discovery complete",
    class="code-string">"discovery": null,
    class="code-string">"started_at": class="code-string">"2026-04-11T12:00:00.000Z",
    class="code-string">"completed_at": null
  },
  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"
  }
}

While the job is still in pending or early discovering, discovery is null. Poll again once current_stage advances past the discovery step.

200Discovery pending

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"status": class="code-string">"discovering",
    class="code-string">"current_stage": class="code-string">"discovering niche and competitors",
    class="code-string">"discovery": null,
    class="code-string">"started_at": class="code-string">"2026-04-11T12:00:00.000Z",
    class="code-string">"completed_at": null
  },
  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-04-11T12:00:10.000Z"
  }
}

404Not found

json

{
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"not_found",
    class="code-string">"message": class="code-string">"No audit job found for slug 'unknown-com'."
  }
}