Agent Integration Guide

AEOForged is an API-first answer-engine-optimization platform with 27 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 when they want — same API, flexible scope.

Last updated 11 June 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).
Outline / write / polish — optional; pass project_id so the human can review in the dashboard.

Example requests (from chat)

“Just get me an outline” — /research → /outline; you write the article.
“Make site copy AI-ready” — /complete-audit, /crawlability, then per-page work in the repo.
“Three promo articles” — three projects, research + outline each; human reviews in the UI.

Playbooks: GET /api/v1/onboard → agent_guidance.playbooks

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 rubric with weights, recommended workflow, and documentation URLs. Read the response fully — it contains scoring rules that directly affect 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.

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. 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; repeat scoring until X-AEO-Score meets your bar.

Iterate

Repeat score / revise · Free scores

Re-score until X-AEO-Score >= 80. 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.

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

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.

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. Improves research quality by 10-20 points
Target 80+ score — the first 5-10 points of improvement have the highest ROI. Don't over-iterate past 90
Total cost: ~10 credits per article — research (10cr) + unlimited free scoring + free schema + free save

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/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)

Project handoff (scoped tokens)

Operators 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 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), 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.

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.

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 } }