Audit Workflow

Diagnose, fix, verify, deliver

Last updated 8 August 2026

A site audit discovers pages, scores each one for answer-engine readiness, and produces a prioritised action queue. This guide walks the loop agents and teams actually use: run diagnose / complete-audit, read the snapshot, claim → fix → done → verify-page, document the fix, then share a report. Updated 2026-08-08.

1. Run the audit

Call the diagnose verb (or the underlying complete_audit tool) to audit a site. By default this returns 202 Accepted with a poll_url because audits take 1–5 minutes depending on site size.

Start the audit

curl -X POST \
  -H "Authorization: Bearer aeo_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteUrl":"https://yoursite.com"}' \
  https://aeoforged.com/api/v1/diagnose

Response (202):

{
  "ok": true,
  "data": {
    "run_id": "uuid",
    "poll_url": "/api/v1/tool-runs/uuid",
    "status": "running"
  }
}

Poll for completion

Check the poll_url periodically. The response includes the current step, progress, and whether the audit is stalled.

curl -H "Authorization: Bearer aeo_sk_YOUR_KEY" \
  https://aeoforged.com/api/v1/tool-runs/{run_id}

When status is "complete", the result field contains the full audit report and the snapshot ID.

Free path vs deeper runs

The free path runs deterministic checks (fetch, AEO score, technical issues) on up to 100 discovered pages, and deep AI analysis on up to 30 non-utility pages. Utility pages stay technical-only. When deep-analysed pages are fewer than technically checked pages, some scorecards have scores but no improvement narrative — that is intentional sampling, not a missing result. Limit: ~3 free audits per day per account.

Credit upgrades: agency (deeper discovery + site planner) and full_depth (LLM-analyse more pages, up to the platform ceiling). Pass include_gaps: true with agency mode for competitive topic gaps. Or pass urls[] to audit an exact page list (portfolio mode — skips discovery; every listed page is deep-analysed within the same ceiling).

2. Read the snapshot

Every audit creates an immutable snapshot — a frozen record of how the site looked at audit time. You can always come back to it. Agents on a handoff token also get a summary via audit_engagement on bootstrap (snapshot id, sampling metadata, queue counts, open backlog, verify-page instructions).

Scorecards

Per-page AEO scores (0–100) across 8 dimensions. Pages are grouped by template cluster (e.g. all /blog/* pages together) with an overall site score.

Sampling label

The report's sampling field shows how many pages were discovered, technically checked, and deep-analysed. When LLM-audited is less than technically checked, some pages have scores but no improvement narrative.

Site plan (agency mode)

With the agency flag, a planner pass deduplicates recommendations across pages. Instead of “add FAQ schema” on every page, you get one sequenced recommendation targeting the right URLs.

Content gaps (optional)

Pass include_gaps: true in agency mode to get competitive topic gap analysis: missing topics, unanswered questions, and suggested new content.

Read a snapshot via API

curl -H "Authorization: Bearer aeo_sk_YOUR_KEY" \
  https://aeoforged.com/api/v1/audit-snapshots/{snapshot_id}

Returns the full report with scorecards, action items, site plan (if agency), and sampling metadata. Add ?format=csv&dataset=scorecards for a CSV export. Handoff tokens are limited to their bound workspace and receive the work plan (effort / impact / status) without pricing fields.

3. Work the action queue

Audit findings become structured action items — each with a type (meta fix, schema, content rewrite, etc.), priority, estimated effort, and acceptance criteria. The agent loop is: claim → apply → done → verify-page → document_fix. REST and MCP share the same transitions (aeo_audit_queue, aeo_action_update, aeo_verify_page, aeo_document_fix).

Step	Status / API	What happens
Claim	`in_progress`	Pick an item from the queue and mark it yours.
Preview fix	`preview-fix`	Optionally generate a proposed diff before editing, so you can inspect what will change.
Fix	(your work)	Apply the fix — edit in your repo, push via CMS, or let an agent handle it.
Done	`done`	Mark the item as fixed. It stays in this state until verified.
Verify	`verify-page`	Re-fetch the live page and re-score against the snapshot baseline. Passing items are promoted automatically.
Verified	`verified`	System-granted status — only verify-page can set this, never a human or agent directly.
Document	`document_fix`	Capture a Remediation Story (problem + fix in your own words). Measured impact is attached later from verify-page evidence — never invented.

Claim an item

curl -X PATCH \
  -H "Authorization: Bearer aeo_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress"}' \
  https://aeoforged.com/api/v1/action-items/{id}

Preview the fix (optional)

Generate a proposed diff without applying it — useful for reviewing before you edit.

curl -X POST \
  -H "Authorization: Bearer aeo_sk_YOUR_KEY" \
  https://aeoforged.com/api/v1/action-items/{id}/preview-fix

Mark done and verify

After fixing, mark the item done, then call verify-page to re-score the live page against the snapshot baseline.

# Mark done
curl -X PATCH -d '{"status":"done"}' ...

# Verify the page
curl -X POST \
  -H "Authorization: Bearer aeo_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yoursite.com/fixed-page","snapshot_id":"uuid"}' \
  https://aeoforged.com/api/v1/verify-page

Document a Remediation Story

After a fix lands, record problem + fix in your own words (free, no LLM). That story can appear on a shared client report; measured score lift is assembled later from verify-page evidence when the item is verified.

curl -X POST \
  -H "Authorization: Bearer aeo_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"problem":"...","fix":"..."}' \
  https://aeoforged.com/api/v1/action-items/{id}/document-fix

Craft over score

Score and verify-page are feedback, not the goal. On marketing, funnel, research, and proof pages, prefer one clear lead, real structure, and honest provenance. Do not stack Key takeaways, question-H2 mirrors, FAQ duplicates, or engine-link stuffing only to move dimensions — a higher AEO score that reads as junk is a failed fix.

Blocked items

If you can't fix something (needs client input, third-party dependency, etc.), set status to blocked with a blocked_reason. Nothing should be silently dropped from the queue.

4. Connect an agent

Instead of (or alongside) fixing things yourself, hand the work to an AI agent in Cursor, Claude Code, or another IDE — or use the Fix Programme surfaces below.

Handoff token

Mint a short-lived, workspace-scoped aeo_ho_ token (from the project handoff dialog, or self-serve from the client room when a Fix Programme window is open). The agent uses this instead of an account API key — scoped to that workspace only.

Bootstrap with audit_engagement

The agent calls GET /api/v1/handoff/{token} once. When a snapshot exists, the response includes audit_engagement: latest snapshot id, sampling metadata, queue counts, prioritised open_items, and verify-page instructions — enough to start the loop without a second discovery pass.

Fix Programme — agent kit

Clients on Fix Programme self-mint a handoff from the room's Connect your agent tab and follow the public aeoforge-fix skill: page-first claim → apply → verify-page → document_fix, with craft over score on live marketing and research pages.

Fix Programme — developer sheet

A no-login checklist at /share/fixes/{token} (aeo_fx_): page-first backlog vs the pinned baseline, per-page verify-page, and the same claim / done / blocked transitions. Mint or revoke links from the client room when the fix window is open.

5. Share results

When work is ready to show externally, share a curated selection of the audit — white-label, no login required. Focus on measured scores, verified fixes, and Remediation Stories; we report score lift, not guaranteed citations.

Curate what stakeholders see

Choose which pages, action items, and report sections appear in the deliverable. You might share a high-level score view with one audience and a concrete fix list with another. Effort estimates and competitor context are optional per share; pricing is never required on a client-facing report.

Share via link

Mint a share link (aeo_sh_ token). Recipients open it in the browser — no AEOForged account needed. Links expire after 30 days by default and can be revoked any time.

Verified fixes and Remediation Stories

Items that pass verify-page are promoted to verified and show progress ticks on the shared report. Stories captured with document_fix can appear as problem → fix → measured proof (proven only when verify-page granted verified; otherwise labelled pending verification).

Before/after comparison

After a second audit over the same site (or the same portfolio URL list), compare snapshots for per-page score deltas. When both runs have pinned research context, the comparison is baseline-comparable; otherwise treat deltas as directional. Prefer measured score lift over ticket counts.

Ready to audit your first site?

Start with a free diagnose call or run one from the dashboard.

Getting Started Agent Integration Guide