REST API Reference

All endpoints require an API key via Authorization: Bearer aeo_sk_... header.

Quick start

1. Create an API key at Settings → API Keys. 2. Score some content (free): curl -X POST -H "Authorization: Bearer aeo_sk_..." -d '{"markdown":"# Test"}' https://aeoforged.com/api/v1/score. 3. See the Prompting Guide for per-tool tips or Workflow Recipes for end-to-end patterns.

Tips for better results

Write detailed briefs. The brief field on research, outline, and pipeline tools dramatically improves output. Include target audience, brand voice, goal, and specific angles (2-3 sentences minimum).
Use deep research for competitive topics. Set depth: "deep" (15cr vs 10cr) for broader multi-angle research on saturated topics.
Pass research into scoring. When calling /api/v1/score, include the research object from your research call to unlock hyper-specific per-section feedback with entity gap detection.
Set contentType correctly. Use "guide" for how-to content (unlocks HowTo schema), "faq" for Q&A content, "article" for standard articles.
Target 80+ score, iterate on feedback. The first 5-10 points of improvement have the highest ROI. Score suggestions tell you exactly what to fix and where — apply them and re-score.
Use workflow tools for multi-step tasks. aeo_workflow_audit_improve, aeo_workflow_strategy, and others combine multiple tools in a single call with automatic error handling.

Base URL: https://aeoforged.com

API version: v1 (stable; breaking changes ship under v2)

Response headers: X-Credits-Charged, X-Credits-Remaining, X-Credits-Remaining-Approximate, Retry-After (on 429), X-Request-Id

Rate limits: Free: 10/min, 100/day | Pro: 60/min | Team: 120/min

Billing semantics: Credits are reserved before the tool runs and refunded on failure. Validation errors (400) and tool errors (500) do not consume credits.

Note: X-Credits-Remaining is approximate — it reflects the balance at request start minus the charge. For an authoritative balance, call GET /api/v1/me.

Error response shape

{
  "ok": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Human-readable reason",
    "upgrade_url": "/settings/billing"
  }
}

Codes

unauthorized (401) — missing or invalid API key
invalid_input / invalid_json (400) — bad request body
insufficient_credits (402) — buy credits or upgrade
rate_limited (429) — see retry_after_seconds
tool_error (500) — upstream failure (no charge)

GET/api/v1/meFree

Whoami: returns auth type, tier, credit balance, and per-tool cost table. Call before paid tools to verify auth and budget.

Request Body

(no body)

Response

{
  "ok": true,
  "data": {
    "user_id": "uuid",
    "auth_type": "api_key",
    "key_id": "uuid",
    "tier": "pro",
    "credits": {
      "included_remaining": 187,
      "balance": 0,
      "total": 187
    },
    "tool_costs": {
      "score": 0,
      "schema": 0,
      "extract": 0,
      "research": 10,
      "research_deep": 15,
      "outline": 3,
      "write_sections": 8,
      "polish": 2,
      "verify": 2,
      "audit": 5,
      "compare": 3,
      "refresh": 8,
      "cluster": 5,
      "full_pipeline": 20,
      "full_pipeline_draft": 12,
      "crawlability": 0,
      "llms_txt": 3,
      "share_of_voice": 10
    }
  },
  "credits_remaining": 187
}

POST/api/v1/scoreFree

Score markdown content for AEO readiness.

Request Body

{
  "markdown": "# Your Article\n\nContent here...",
  "hasJsonLd": false,
  "entities": ["entity1", "entity2"]
}

Response

{
  "ok": true,
  "data": {
    "total": 72,
    "breakdown": [
      { "name": "Direct Answer", "score": 80, "max": 100, "details": "..." }
    ],
    "suggestions": [
      { "dimension": "Schema", "suggestion": "Add JSON-LD structured data" }
    ]
  },
  "credits_remaining": 200
}

POST/api/v1/schemaFree

Generate JSON-LD structured data from a title and outline.

Request Body

{
  "title": "Your Article Title",
  "outline": {
    "title": "Your Article Title",
    "sections": [
      {
        "h2": "Section Title",
        "intent": "informational",
        "directAnswer": "The concise answer.",
        "eatSlots": ["expertise"]
      }
    ]
  }
}

Response

{
  "ok": true,
  "data": {
    "schemas": [
      { "@context": "https://schema.org", "@type": "Article", ... }
    ]
  }
}

POST/api/v1/research10/15 credits

Run live web research. Standard (10cr) or deep mode (15cr, more queries + gpt-4o). Supports geo/language targeting and recency bias.

Request Body

{
  "keyword": "answer engine optimization",
  "brief": "Optional brand/audience context",
  "depth": "standard",
  "region": "US",
  "language": "en",
  "recency": true
}

Response

{
  "ok": true,
  "data": {
    "entities": ["AEO", "Google AI Overviews", ...],
    "claimsSupportedBySources": [...],
    "dataPoints": [...],
    "topUrls": [...]
  },
  "credits_remaining": 190
}

POST/api/v1/outline3 credits

Generate a structured content outline from research data.

Request Body

{
  "topic": "answer engine optimization",
  "research": { ... },
  "contentType": "article",
  "brief": "Optional context"
}

Response

{
  "ok": true,
  "data": {
    "title": "Understanding Answer Engine Optimization",
    "sections": [...]
  },
  "credits_remaining": 187
}

POST/api/v1/write8 credits

Write full article sections from outline and research, with verified citations, tone/voice control, and coherence pass.

Request Body

{
  "outline": { "title": "...", "sections": [...] },
  "research": { ... },
  "contentType": "article",
  "tone": "professional",
  "readingLevel": "general"
}

Response

{
  "ok": true,
  "data": {
    "sections": [...],
    "markdown": "## Section 1\n\nContent...",
    "citations": [{ "url": "https://...", "howUsed": "..." }]
  }
}

POST/api/v1/polish2 credits

Style and cleanup pass with changelog, heading preservation, brand voice, and idempotency guard.

Request Body

{
  "markdown": "## Section\n\nContent...",
  "contentType": "article",
  "brandVoice": "Never use passive voice",
  "targetReadingLevel": 8
}

Response

{
  "ok": true,
  "data": {
    "markdown": "## Section\n\nPolished content...",
    "changesApplied": ["Shortened sentences", "Removed passive voice"],
    "removedCitations": [],
    "headingCheck": { "preserved": true }
  }
}

POST/api/v1/verify2 credits

Cross-reference claims against research. Returns confidence tiers, verification report, and structural integrity check.

Request Body

{
  "markdown": "Article content...",
  "research": { ... }
}

Response

{
  "ok": true,
  "data": {
    "markdown": "Verified content...",
    "claimsRemoved": [...],
    "claimsQualified": [...]
  }
}

POST/api/v1/generate12/20 credits

Run the full pipeline. Draft mode (12cr): research → outline → write → score. Publish mode (20cr): adds polish + verify. Pass pre-computed research to save 10cr.

Request Body

{
  "keyword": "answer engine optimization",
  "brief": "Optional context",
  "contentType": "article",
  "mode": "publish"
}

Response

{
  "ok": true,
  "data": {
    "markdown": "# Article Title\n\n...",
    "html": "<h1>Article Title</h1>...",
    "jsonLd": [...],
    "schemaTypes": ["Article", "FAQPage"],
    "score": { "total": 85, ... },
    "sources": [...],
    "research": { ... },
    "completedSteps": ["research", "outline", "write", "polish", "verify", "score", "html"]
  }
}

POST/api/v1/audit5 credits

Fetch a URL, score it for AEO readiness, and get a prioritized improvement plan. Optionally provide a target keyword for competitive analysis.

Request Body

{
  "url": "https://example.com/article",
  "targetKeyword": "answer engine optimization",
  "brief": "Optional brand context"
}

Response

{
  "ok": true,
  "data": {
    "url": "https://example.com/article",
    "extractedWordCount": 1250,
    "score": { "total": 62, "breakdown": [...], "suggestions": [...] },
    "improvements": [
      { "priority": "high", "category": "Structure", "description": "Add question-format H2 headings", "estimatedImpact": 8 }
    ],
    "missingEntities": ["Google SGE", "Perplexity"],
    "schemaOpportunities": ["FAQPage", "HowTo"],
    "contentStrengths": [...],
    "contentWeaknesses": [...]
  }
}

POST/api/v1/compare3 credits

Compare two articles head-to-head across all 8 AEO dimensions. Provide URLs or markdown for each.

Request Body

{
  "contentA": { "url": "https://example.com/our-article" },
  "contentB": { "url": "https://competitor.com/their-article" },
  "targetKeyword": "answer engine optimization"
}

Response

{
  "ok": true,
  "data": {
    "scoreA": { "total": 78, ... },
    "scoreB": { "total": 62, ... },
    "winner": "A",
    "dimensionComparison": [
      { "category": "Structure", "scoreA": 21, "scoreB": 12, "winner": "A", "insight": "..." }
    ],
    "summary": "Content A significantly outperforms...",
    "aStrengths": [...],
    "bStrengths": [...],
    "recommendations": [...]
  }
}

POST/api/v1/refresh8 credits

Analyze existing content against fresh research. Returns a targeted update plan with outdated data flagged.

Request Body

{
  "url": "https://example.com/old-article",
  "keyword": "content marketing strategy",
  "brief": "Optional context"
}

Response

{
  "ok": true,
  "data": {
    "currentScore": { "total": 55, ... },
    "projectedScore": 72,
    "freshResearch": { ... },
    "updatePlan": [
      { "section": "What is content marketing?", "action": "update", "priority": "high", "reason": "Outdated 2023 statistic" }
    ],
    "outdatedDataPoints": [...],
    "missingEntities": [...],
    "missingAngles": [...],
    "recencyIssues": [...]
  }
}

POST/api/v1/cluster5 credits

Group keywords by semantic similarity. Returns clusters with pillar/supporting hierarchy and a prioritized content calendar.

Request Body

{
  "keywords": ["what is SEO", "SEO basics", "keyword research tools", "technical SEO checklist"],
  "domain": "example.com",
  "maxClusters": 5
}

Response

{
  "ok": true,
  "data": {
    "clusters": [
      { "name": "SEO Fundamentals", "pillarKeyword": "what is SEO", "supportingKeywords": [...], "searchIntent": "informational", ... }
    ],
    "hierarchy": [{ "pillar": "what is SEO", "clusters": ["SEO Fundamentals"] }],
    "contentCalendar": [
      { "keyword": "what is SEO", "cluster": "SEO Fundamentals", "priority": 10, "contentType": "guide", "suggestedTitle": "..." }
    ],
    "totalKeywords": 4,
    "totalClusters": 2
  }
}

POST/api/v1/extractFree

Reformat markdown for answer engine extraction. Returns featured snippet, knowledge panel, and People Also Ask formats. Free, instant.

Request Body

{
  "markdown": "## What is AEO?\n\nAnswer Engine Optimization is...",
  "format": "all"
}

Response

{
  "ok": true,
  "data": {
    "featuredSnippet": { "definition": "Answer Engine Optimization is...", "listItems": [...] },
    "knowledgePanel": { "name": "AEO", "description": "...", "attributes": [...] },
    "peopleAlsoAsk": [{ "question": "What is AEO?", "answer": "..." }],
    "extractabilityScore": 8,
    "suggestions": [...]
  }
}

POST/api/v1/trackFree

Register a URL for citation monitoring across Brave, Google AI, and Perplexity. Requires a keyword and project_id. Tracking is included with Pro.

Request Body

{
  "url": "https://example.com/my-article",
  "keyword": "answer engine optimization",
  "project_id": "uuid",
  "article_id": "uuid (optional)",
  "score": 82,
  "score_breakdown": { ... },
  "alert_threshold": 10
}

Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "url": "https://example.com/my-article",
    "keyword": "answer engine optimization",
    "status": "active",
    "created_at": "2026-05-08T12:00:00Z"
  }
}

GET/api/v1/track/statusFree

Get all tracked URLs with current monitoring data including latest citation status, position, and score.

Request Body

(no body)

Response

{
  "ok": true,
  "data": [
    {
      "id": "uuid",
      "url": "https://example.com/my-article",
      "keyword": "answer engine optimization",
      "latest_check": { "cited": true, "position": 3, "engine": "perplexity" },
      "score": 82,
      "alert_threshold": 10,
      "status": "active"
    }
  ]
}

GET/api/v1/track/[id]/historyFree

Get check history for a specific tracked URL. Returns all citation checks with position, engine, and timestamp.

Request Body

(no body)

Response

{
  "ok": true,
  "data": {
    "tracked_url": { "id": "uuid", "url": "https://example.com/my-article", "keyword": "..." },
    "checks": [
      { "checked_at": "2026-05-08T12:00:00Z", "engine": "perplexity", "cited": true, "position": 3, "snippet": "..." }
    ]
  }
}

GET/api/v1/alertsFree

Get unread alerts. Supports ?count_only=true to return just the unread count for badge display.

Request Body

(no body — query param: ?count_only=true)

Response

{
  "ok": true,
  "data": [
    {
      "id": "uuid",
      "type": "citation_found",
      "tracked_url_id": "uuid",
      "message": "First citation detected on Perplexity for ...",
      "created_at": "2026-05-08T12:00:00Z",
      "read": false
    }
  ]
}

POST/api/v1/alerts/readFree

Mark one or more alerts as read. Pass an array of alert IDs.

Request Body

{
  "alert_ids": ["uuid1", "uuid2"]
}

Response

{
  "ok": true,
  "data": { "marked": 2 }
}

GET/api/v1/platform/statsFree

Latest platform analytics — total articles generated, average scores, citation rates. Public endpoint, no auth required.

Request Body

(no body — no auth required)

Response

{
  "ok": true,
  "data": {
    "total_articles": 12400,
    "avg_score": 78.3,
    "total_citations_tracked": 5200,
    "citation_rate": 0.42
  }
}

GET/api/v1/case-studiesFree

Get opt-in case studies showcasing before/after AEO scores and citation outcomes. Public endpoint, no auth required.

Request Body

(no body — no auth required)

Response

{
  "ok": true,
  "data": [
    {
      "id": "uuid",
      "url": "https://example.com/article",
      "keyword": "...",
      "before_score": 55,
      "after_score": 88,
      "citations": 3,
      "opted_in_at": "2026-05-01T00:00:00Z"
    }
  ]
}

POST/api/v1/case-studies/opt-inFree

Toggle case study opt-in for a tracked URL. Opted-in URLs appear on the public case studies page.

Request Body

{
  "tracked_url_id": "uuid",
  "opt_in": true
}

Response

{
  "ok": true,
  "data": { "tracked_url_id": "uuid", "opted_in": true }
}

POST/api/v1/workflow/audit-improve5-13 credits

Workflow: audits a URL then generates a refresh plan if score is below threshold. Combines audit (5cr) + refresh (8cr).

Request Body

{
  "url": "https://example.com/article",
  "keyword": "target keyword",
  "brief": "Brand context",
  "skipRefreshIfAbove": 80
}

Response

{
  "ok": true,
  "data": {
    "audit": { "url": "...", "score": { "total": 72, ... }, "improvements": [...] },
    "refresh": { "currentScore": {...}, "projectedScore": 85, "updatePlan": [...] },
    "totalCreditsUsed": 13,
    "completedSteps": ["audit", "refresh"]
  },
  "credits_charged": 13,
  "credits_remaining": 87
}

POST/api/v1/workflow/strategy~44 credits

Workflow: clusters keywords, then researches and outlines the top N pillar topics. Combines cluster (5cr) + research (10cr each) + outline (3cr each).

Request Body

{
  "keywords": ["what is SEO", "SEO basics", "keyword research tools"],
  "domain": "example.com",
  "maxClusters": 5,
  "researchTopN": 3,
  "brief": "SaaS blog targeting developers"
}

Response

{
  "ok": true,
  "data": {
    "clusters": [...],
    "pillars": [
      { "keyword": "what is SEO", "research": {...}, "outline": {...} }
    ],
    "totalCreditsUsed": 44,
    "completedSteps": ["cluster", "research", "outline"]
  },
  "credits_charged": 44,
  "credits_remaining": 56
}

POST/api/v1/workflow/health5/URL credits

Workflow: batch-audit up to 10 URLs and return a sorted priority dashboard with per-URL scores and improvement plans.

Request Body

{
  "urls": [
    "https://example.com/article-1",
    "https://example.com/article-2",
    "https://example.com/article-3"
  ],
  "targetKeyword": "content marketing"
}

Response

{
  "ok": true,
  "data": {
    "results": [
      { "url": "...", "score": { "total": 45, ... }, "improvements": [...] }
    ],
    "sorted": true,
    "totalUrls": 3,
    "averageScore": 58,
    "totalCreditsUsed": 15,
    "completedSteps": ["audit_batch"]
  },
  "credits_charged": 15,
  "credits_remaining": 85
}

POST/api/v1/workflow/quality-gateFree

Workflow: score content against a target threshold. Returns pass/fail with actionable fixes if below threshold. Free — no credits charged.

Request Body

{
  "markdown": "# Your Article\n\nContent here...",
  "targetScore": 75,
  "entities": ["entity1", "entity2"]
}

Response

{
  "ok": true,
  "data": {
    "passed": false,
    "score": { "total": 68, "breakdown": [...] },
    "targetScore": 75,
    "gap": 7,
    "fixes": [
      { "dimension": "Structure", "suggestion": "Add question-format H2 headings", "estimatedImpact": 5 }
    ],
    "completedSteps": ["score", "evaluate"]
  },
  "credits_charged": 0,
  "credits_remaining": 100
}

POST/api/v1/crawlabilityFree

AI Crawlability Check: analyse a website for AI bot access. Checks robots.txt for 11 AI bots (GPTBot, ClaudeBot, PerplexityBot, etc.), meta directives, llms.txt presence, sitemap, and JS rendering.

Request Body

{
  "siteUrl": "https://example.com"
}

Response

{
  "ok": true,
  "data": {
    "siteUrl": "https://example.com",
    "checkedAt": "2026-05-10T...",
    "overallStatus": "partial",
    "robotsTxt": { "exists": true, "blockedBots": [...], "allowedBots": [...] },
    "metaTags": { "hasNoai": false, "hasNoimageai": false },
    "xRobotsTag": { "present": false },
    "llmsTxt": { "exists": false },
    "sitemap": { "exists": true, "url": "..." },
    "jsRendering": { "heavyJs": false },
    "recommendations": [
      { "severity": "high", "title": "...", "description": "...", "fix": "..." }
    ]
  },
  "credits_charged": 0,
  "credits_remaining": 100
}

POST/api/v1/llms-txt3 credits

Generate spec-compliant llms.txt and llms-full.txt files for a website. Auto-discovers pages, groups them into semantic sections via AI, and provides deployment instructions.

Request Body

{
  "siteUrl": "https://example.com"
}

Response

{
  "ok": true,
  "data": {
    "siteUrl": "https://example.com",
    "generatedAt": "2026-05-10T...",
    "llmsTxt": "# example.com\n> Company description...\n\n## Docs\n- [Page Title](url): description\n...",
    "llmsFullTxt": "# example.com\n> Full version with all pages...\n...",
    "pages": [
      { "url": "https://...", "title": "...", "section": "Docs", "description": "..." }
    ],
    "deploymentInstructions": "1. Save as /llms.txt in your site root..."
  },
  "credits_charged": 3,
  "credits_remaining": 97
}