What AI crawlers get when they fetch your site, and how your pages compare with the pages engines cite.
GET /brands/{brandId}/crawl-truth
What AI crawlers get when they fetch your site.
About this route
Detail
Returns
capturedAt; probes: per AI crawler user agent, what your site served it next to a normal visitor; readability: per page, the words a crawler reads without running JavaScript against the rendered page; robots: the robots.txt rule for each crawler.
capturedAt; probes: per AI crawler user agent, what your site served it next to a normal visitor; readability: per page, the words a crawler reads without running JavaScript against the rendered page; robots: the robots.txt rule for each crawler.
400
An id in the path is not a valid id.
401
No valid API key was sent.
404
No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
POST /brands/{brandId}/crawl-truth
Queue the crawler probe and the readability capture.
About this route
Detail
Returns
queued: true and jobId. The work runs in the background; read the matching GET route for the result.
Seat
A key on a member seat or above. A viewer's key is refused with 403.
Plan
Every plan.
Rate limit
30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget
Checked before the work starts: 429 once the workspace's spend safety limit is reached.
Parameter
Type
What it is
brandId (path, required)
uuid
A brand id from GET /brands.
curl -X POST "https://api.ansengine.co/brands/{brandId}/crawl-truth" \
-H "Authorization: Bearer ak_your_key"
Status
When
200
queued: true and jobId. The work runs in the background; read the matching GET route for the result.
400
An id in the path is not a valid id.
401
No valid API key was sent.
403
The key belongs to a viewer seat, which can read and cannot write.
404
No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
429
Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait. Or the workspace's spend safety limit is reached: the body says so as budget_cap_reached, and spend resumes next cycle.
GET /brands/{brandId}/content/drafts/{draftId}/content-score
A Studio draft's content score: how it covers what the pages AI cited for its brief's prompt cover.
Note
A comparison with the pages AI cited for this prompt, not a forecast of whether a page gets cited. Built from stored answers and stored page reads: a page not read yet is said to be unread and is never fetched for this. Fewer than 3 read pages give no score.
About this route
Detail
Returns
state (scored, no_prompt or too_few_pages) and sentence; score: total from 0 to 100, each part with its weight, points, count and lines, and the shared topics with whether the draft covers each; reference: the pages cited in the last 30 days, each with its models, answer count and read state; weights; revisions, each scored on read.
state (scored, no_prompt or too_few_pages) and sentence; score: total from 0 to 100, each part with its weight, points, count and lines, and the shared topics with whether the draft covers each; reference: the pages cited in the last 30 days, each with its models, answer count and read state; weights; revisions, each scored on read.
400
An id in the path is not a valid id.
401
No valid API key was sent.
404
No such brand or draft for this key.
GET /brands/{brandId}/content/briefs/{briefId}/cited-pages
What the pages AI cited for a brief's prompt cover.
About this route
Detail
Returns
briefId; reference (null when the brief names no prompt): the pages cited in the last 30 days with their models, answer counts and read state, and the topics two or more read pages share; sentence when there is nothing to compare.
briefId; reference (null when the brief names no prompt): the pages cited in the last 30 days with their models, answer counts and read state, and the topics two or more read pages share; sentence when there is nothing to compare.
400
An id in the path is not a valid id.
401
No valid API key was sent.
404
No such brand or brief for this key.
GET /brands/{brandId}/onpage
The site retrievability report, findings ordered by the traffic of the page each sits on.
About this route
Detail
Returns
report (null before the first crawl), weighted and headline. Findings are ordered by the Search Console traffic of their page when Search Console is connected; a page with no measured traffic reads null, never zero.
report (null before the first crawl), weighted and headline. Findings are ordered by the Search Console traffic of their page when Search Console is connected; a page with no measured traffic reads null, never zero.
400
An id in the path is not a valid id.
401
No valid API key was sent.
404
No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
POST /brands/{brandId}/onpage
Queue the site crawl.
Note
The page cap is set before the crawl starts, and it is the cost cap.
About this route
Detail
Returns
queued: true and jobId. The work runs in the background; read the matching GET route for the result.
Seat
A key on a member seat or above. A viewer's key is refused with 403.
Plan
Every plan.
Rate limit
30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget
Checked before the work starts: 429 once the workspace's spend safety limit is reached.
Parameter
Type
What it is
brandId (path, required)
uuid
A brand id from GET /brands.
curl -X POST "https://api.ansengine.co/brands/{brandId}/onpage" \
-H "Authorization: Bearer ak_your_key"
Status
When
200
queued: true and jobId. The work runs in the background; read the matching GET route for the result.
400
An id in the path is not a valid id.
401
No valid API key was sent.
403
The key belongs to a viewer seat, which can read and cannot write.
404
No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
429
Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait. Or the workspace's spend safety limit is reached: the body says so as budget_cap_reached, and spend resumes next cycle.
POST /page-audits/{auditId}/share
Make a link to one page's audit that anyone with it can open, replacing the link it had.
Note
auditId is a page's id from the site audit. One live link per audit: sharing again ends the old link. expiresInDays is 7, 30 or 90, or null for a link that never expires. An admin revokes a link in the console.
About this route
Detail
Returns
token (shown once and never stored: only its hash is kept), path (the link's path on the report site, /report/page/{token}) and share (prefix, createdAt, expiresAt, expired, lastOpenedAt). The link opens that page's audit under the workspace's white label, and nothing else of the workspace.
Seat
A key on a member seat or above. A viewer's key is refused with 403.
Plan
Every plan.
Rate limit
30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget
Nothing this route does is metered.
Parameter
Type
What it is
auditId (path, required)
uuid
The audit id.
The body is JSON. Its schema, taken from the route's own validation:
token (shown once and never stored: only its hash is kept), path (the link's path on the report site, /report/page/{token}) and share (prefix, createdAt, expiresAt, expired, lastOpenedAt). The link opens that page's audit under the workspace's white label, and nothing else of the workspace.
400
auditId is not a valid id, or the body does not match the schema.
401
No valid API key was sent.
403
The key belongs to a viewer seat, which can read and cannot write.
404
No such page audit for this key. An audit of a client outside this seat's view answers the same way.
429
Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait.
POST /brands/{brandId}/onpage/benchmark
Compare one of your pages with the pages engines were seen citing, on the same checks.
Note
The page must be on one of the brand's own domains. Fetching pages costs no engine budget, so the route is rate limited instead.
About this route
Detail
Returns
benchmark (your score, the cited pages' median score, and the gaps and strengths found) and headline.
Seat
A key on a member seat or above. A viewer's key is refused with 403.
Plan
Every plan.
Rate limit
30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget
Nothing this route does is metered.
Parameter
Type
What it is
brandId (path, required)
uuid
A brand id from GET /brands.
The body is JSON. Its schema, taken from the route's own validation:
benchmark (your score, the cited pages' median score, and the gaps and strengths found) and headline.
400
An id in the path is not valid, the body has no valid url, or the url is not on one of the brand's domains.
401
No valid API key was sent.
403
The key belongs to a viewer seat, which can read and cannot write.
404
No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
429
Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait.
