Agent Integration Guide

AEOForged is an API-first answer-engine-optimization platform with 30 tools covering the full content lifecycle. Agents write and ship copy in the IDE while AEOForged grounds the facts and measures readiness; the human reviews in the dashboard or client room when they want — same API, flexible scope.

Updated 2026-08-08 · Skills: /docs/skills · /for-agents · /start · /pricing

Last updated 8 August 2026

How agents should think about tools

Match the user's ask — outline-only, IDE writing, hosted draft, or site-wide audit. Do not run the full pipeline unless they ask.
Research + score — grounded facts and measurable fixes (core loop).
Craft over score — scoring is feedback, not the product. Refuse FAQ / Key-takeaways / question-H2 stacks added only to move dimension numbers.
Outline / write / polish — optional; pass project_id so the human can review in the dashboard.

Credentials

Prefix	Scope	Bootstrap
aeo_sk_	Account API key	`GET /api/v1/onboard?workspace_id=`
aeo_ho_	Workspace handoff (short-lived)	`GET /api/v1/handoff/{token}`

Use the credential as Authorization: Bearer … on REST and MCP. Handoff tokens are bound to one Project — no account key required. Humans mint them from the dashboard or the client room's Connect your agent tab (Fix Programme).

Agent-first packages & skills

Load the public skill that matches the job (full list and install paths on /docs/skills):

Free audit (no key yet) — aeoforge-free-audit or the copyable prompt at /for-agents
Ongoing after a package — aeoforge-selfserve with aeo_sk_
Fix Programme — aeoforge-fix + handoff token from the room

After bootstrap, follow next_task from onboard or handoff. Fetch the assigned pack with GET /api/v1/agent-tasks/{pack_id}. Do not invent a parallel menu — the server routes the work.

Example requests (from chat)

“Just get me an outline” — /research → /outline; you write the article.
“Make site copy AI-ready” — /complete-audit or /diagnose, /crawlability, then per-page work in the repo.
“Three promo articles” — three projects, research + outline each; human reviews in the UI.
“Set me up on AEOForge” — free-audit skill or /for-agents prompt; stop at wait_payment.

GET /api/v1/onboard returns this Project's state and the next step. Every tool response carries a next field: the next call, or that you are done.

Gates agents must respect

Grounding gate

Finished content must cite research-allow-listed sources. POST /api/v1/write returns 422 research_required without research; submit-for-review and final: true saves return 422 ungrounded_content. Shortcut: aeo_create researches, drafts, and grounds in one call.

Score bar (80)

POST /api/v1/projects/{id}/submit-for-review rejects scores below 80 with 422 below_score_bar. Iterate with free /score (and optional improve) until the bar clears. Craft still wins — do not junk the page to hit 80.

Decision gate

Durable human questions: MCP aeo_ask_human or POST/GET /api/v1/decisions. Poll until action: "proceed". Wait means stop — do not retry the work or skip ahead. Brand Confirm, payment, and package selection stay human-only forever.

The workflow

Onboard

GET /api/v1/onboard · Free

Before using any tool, call this endpoint to receive the full product context: tool catalog with costs, 8-dimension scoring dimensions and tips, recommended workflow, next_task when a workspace is set, and documentation URLs. Read the response fully — it contains scoring guidance that directly affects content quality.

curl -H "Authorization: Bearer $KEY" \
  https://aeoforged.com/api/v1/onboard

Research

POST /api/v1/research · 10cr

Get entities, source-backed claims, data points, competitor angles, and open questions. Include a detailed brief for better results. Required before finished-content boundaries (grounding gate).

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"AEO optimization","brief":"For content marketers at B2B SaaS companies","depth":"standard"}' \
  https://aeoforged.com/api/v1/research

Author (pick one path)

/outline + /write + optional /polish — or your model · 0–20cr

Either draft locally (free) or call hosted outline/write/polish so drafts land in the workspace. Cite only research-allow-listed URLs. Then continue with scoring.

Score

POST /api/v1/score · Free

Get 8-dimension, page-type-aware feedback (Structure, Direct Answer, Schema, Entity, E-E-A-T, Recency, Readability, Extractability). Pass `markdown` for a local draft, or `url` to score the LIVE page (single source of truth — no shadow copy). Check X-AEO-Score, X-AEO-Page-Type, and X-AEO-Weakest headers for fast iteration.

# Score a local draft
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown":"# Your Article...","research":{...from step 1...}}' \
  "https://aeoforged.com/api/v1/score?fields=total,suggestions"

# …or score the live published page
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yoursite.com/blog/post"}' \
  "https://aeoforged.com/api/v1/score"

Revise

Hosted tools and/or your model · Free or metered

Apply suggestions from /score. Edit locally or re-run hosted passes; prefer real structure and voice over detector-bait chrome. Repeat scoring until X-AEO-Score meets the bar.

Iterate to 80+

Repeat score / revise · Free scores

Re-score until X-AEO-Score >= 80 (required for submit-for-review). Typical articles reach 80+ in 2–3 iterations. Each score call is free.

Schema

POST /api/v1/schema · Free

Generate Article + FAQ + HowTo JSON-LD structured data. Call after your content is finalized.

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Your Title","outline":{...},"finalMarkdown":"..."}' \
  https://aeoforged.com/api/v1/schema

Save

POST /api/v1/projects · Free

Persist your finished article to the user's AEOForged workspace. Returns a project_id and dashboard URL. Default saves may return a grounding warning; final: true enforces the grounding gate.

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Article Title","keyword":"aeo","markdown":"...","research":{...}}' \
  https://aeoforged.com/api/v1/projects

Submit for review (gate)

POST /api/v1/projects/{id}/submit-for-review · Free

Hard finished boundary: grounding + score ≥ 80. Then GET …/gate-status at most twice. action "wait" means stop and tell the human to prompt you after they respond; "apply_feedback_and_resubmit" → revise and re-submit; "publish_and_track" → continue.

curl -X POST -H "Authorization: Bearer $KEY" \
  https://aeoforged.com/api/v1/projects/PROJECT_ID/submit-for-review

Hosted authoring endpoints

These are available to API key callers (same as session). Credits are charged per call; see GET /api/v1/onboard for current costs. Pass project_id on outline/write when you want the dashboard to update.

POST /api/v1/outline — structured outline from research
POST /api/v1/write — hosted section-by-section draft
POST /api/v1/polish — polish pass with changelog
POST /api/v1/generate — full pipeline (draft or publish mode)

MCP equivalents: aeo_outline, aeo_write, aeo_polish, aeo_full_pipeline. Prefer consolidated verbs for new work: aeo_create, aeo_improve, aeo_package, aeo_diagnose.

Response headers

Header	Endpoint	Description
X-AEO-Score	/score, /projects	Overall AEO score (0-100)
X-AEO-Weakest	/score	Comma-separated weakest dimensions
X-AEO-Next-Step	/score, /research	Contextual guidance on what to do next
X-Expected-Duration	/research	Estimated seconds for the research call
X-Credits-Charged	All	Credits deducted for this call
X-Credits-Remaining	All	Approximate remaining credit balance

Tips for fast iteration

Use ?fields=total,suggestions on /score — skip the full breakdown and get just what you need to iterate
Pass research into /score — unlocks per-section entity gap detection and competitor coverage analysis
Write a detailed brief — audience, tone, goal, required angles improve research relevance
Target 80+ score — the submit-for-review bar; stop polishing once the page is clear and grounded rather than chasing every point past 90
Typical research-first article: ~10 credits — research (10cr) + unlimited free scoring + free schema + free save (hosted write/polish add credits when used)

Also available for agents

These intelligence tools are fully available for API key callers:

POST /api/v1/audit — audit any URL (5cr)
POST /api/v1/diagnose — site-wide audit (free, async)
POST /api/v1/compare — compare articles (3cr)
POST /api/v1/refresh — refresh plan (8cr)
POST /api/v1/cluster — keyword clustering (5cr)
POST /api/v1/extract — snippet formats (free)
POST /api/v1/track — citation monitoring (free)
POST /api/v1/crawlability — AI crawlability check (free)
POST /api/v1/llms-txt — llms.txt generator (3cr)
POST /api/v1/share-of-voice — Share of Voice tracker (10cr)
POST /api/v1/factcheck — deterministic stat check (free)
POST /api/v1/moat-check — competitive gap analysis (15cr)
POST /api/v1/agent-ready — agent readiness audit (free)
POST /api/v1/decisions — aeo_ask_human

Project handoff (scoped tokens)

Humans can hand a specific Project to an external agent using a short-lived, workspace-scoped handoff token (prefix aeo_ho_). The token is minted from the dashboard or the client room and scopes the agent to one workspace — no account API key needed.

Bootstrap

GET /api/v1/handoff/{token} · Free

One-call bootstrap: resolves the token into workspace + client brief, article list, credits, MCP config, work access (git, CMS, GitHub PR), next_task, and — when an audit snapshot exists — audit_engagement with queue summary and verify-page instructions.

curl -H "Authorization: Bearer aeo_ho_YOUR_TOKEN" \
  https://aeoforged.com/api/v1/handoff/aeo_ho_YOUR_TOKEN

Claim an action item

PATCH /api/v1/action-items/{id} · Free

Set status to "in_progress" to claim an item from the audit queue. The agent works on fixes — in the repo, via CMS, or through a GitHub PR. Prefer page-first Fix Programme loops from next_task when present.

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

Mark done (not "verified")

PATCH /api/v1/action-items/{id} · Free

Set status to "done" when you have applied the fix. If blocked, set "blocked" with a blocked_reason. Never set "verified" — that status is system-only, granted by verify-page.

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

Verify the fix

POST /api/v1/verify-page · Free

Re-fetches the live page, re-scores against the snapshot baseline, and runs deterministic checks. Items that pass are promoted from "done" to "verified" by the system. If checks fail, the item stays "done" — reopen it and fix. Craft over score still applies on marketing and research pages.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page","snapshot_id":"SNAPSHOT_ID"}' \
  https://aeoforged.com/api/v1/verify-page

"verified" is system-only

Agents must never set status: "verified" directly. The PATCH endpoint rejects it with 422. The only writer is POST /api/v1/verify-page, which re-fetches the live page, re-scores against the snapshot's pinned research context, and promotes passing items. This ensures every "verified" claim is backed by a measured re-check.

Async polling (long-running tools)

Long-running tools (diagnose, visibility, research) return 202 with a run_id and poll_url by default.

Polling workflow

Call the tool — receive X-Tool-Run-Id header (REST) or run_id in the MCP response
Poll GET /api/v1/tool-runs/{run_id} periodically
Check status: "running" (wait), "complete" (read result), "error" (read error), "timeout" (retry)
If likely_stalled: true — the tool may have crashed; consider retrying

curl -H "Authorization: Bearer $KEY" \
  https://aeoforged.com/api/v1/tool-runs/RUN_ID
# → { "status": "running", "step": "auditing_pages", "progress": { "current": 5, "total": 12 } }