Agent Integration Guide

AEOForged is the intelligence layer for Cursor, Claude Code, and other agents. You write and ship copy in the IDE; AEOForged supplies research, outlines, scoring, audits, and schema. The human reviews in the dashboard when they want — same API, flexible scope.

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)