Audit Workflow

Diagnose, fix, verify, deliver

Last updated 19 June 2026

A site audit discovers every page, scores each one for answer-engine readiness, benchmarks against competitors, and produces a prioritised action queue. This guide walks through the full loop: running an audit, reading the results, fixing issues, verifying that fixes landed, and sharing a report with stakeholders.

1. Run the audit

Call the diagnose verb (or the underlying complete_audit tool) to audit an entire 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 tier limits

Free audits discover up to 30 pages and deep-analyze every non-utility page in that set (AEO scoring + LLM improvement plan). Utility pages stay technical-only. Larger runs may continue across a short batch. Limit: ~3 free audits per day per account.

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.

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 LLM-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.

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. Work through them in order.

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.

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

Blocked items

If you can't fix something (needs client input, third-party dependency, etc.), set status to blocked with a blocked_reason. The dashboard surfaces these so nothing gets silently dropped.

4. Connect an agent

Instead of (or alongside) fixing things yourself, you can hand the work to an AI agent running in Cursor, Claude Code, or another IDE.

Mint a handoff token

From the project page, click “Hand off to agent” to generate a short-lived, workspace-scoped aeo_ho_ token. The agent uses this instead of your API key — it can only access that project and bills to your account.

Agent activity

Every tool call the agent makes is automatically streamed to the activity panel in the dashboard. You can watch what it's doing in real time without any extra setup.

Work access

Configure how the agent applies fixes at Project → Settings → Work Access: direct CMS write (WordPress, Shopify), GitHub PR (code sites), or dashboard-only (you apply manually).

Agent bootstrap

The agent calls GET /api/v1/handoff/{token} once to get everything it needs: project context, audit queue, MCP config, and next steps.

5. Deliver results to your client

Once work is done, create a curated selection of the audit results to share externally. Clients see a white-label report — no login required.

Create a curation

From the snapshot dashboard, select which pages, action items, and report sections to include. You might create one curation for the CMO (high-level scores) and another for the dev team (specific fixes).

Control what's visible

Section toggles let you show or hide prices, effort estimates, competitor data, and the site plan per curation. Defaults: prices off, effort on.

Share via link

Mint a share link (aeo_sh_ token) for the curation. The client opens it in their browser — no AEOForged account needed. Links expire after 30 days by default and can be revoked any time.

Before/after proof (snapshot diff)

After a second audit, open Compare with previous audit on the snapshot dashboard (/audits/[newId]/diff/[previousId]). Per-page score deltas are sorted by magnitude — use this for sprint deliverables and renewal conversations. We report score lift, not guaranteed citations.

Convert backlog to an order

From the curation builder, select remaining action items and use Convert to order with your org rate card. Items without a rate land in needs_manual_price — never silently at $0.

Verified fixes show progress

Items that pass verify-page are promoted to verified and show progress ticks on the shared report. Clients see work getting done without you sending updates.

Ready to audit your first site?

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

Getting Started Agent Integration Guide