AEOForgedAEOForged
Join

REST API Reference

The AEOForged REST API is an HTTPS, JSON API that gives developers and AI agents programmatic access to 29 tools plus consolidated verbs — research, scoring, grounded drafting, site diagnosis, authority, original research, and measured citation monitoring. Responses use a consistent { ok, data } envelope.

Authenticate with Authorization: Bearer aeo_sk_... (account API key) or Bearer aeo_ho_... (short-lived project handoff). For the live tool list and costs, call GET /api/v1/onboard and GET /api/v1/me — this page is a guide, not the source of truth for pricing.

Last updated

Quick start

1. Create an API key at Settings → API Keys. 2. Bootstrap: curl -H "Authorization: Bearer aeo_sk_..." https://aeoforged.com/api/v1/onboard. 3. Score some content (free): curl -X POST -H "Authorization: Bearer aeo_sk_..." -d '{"markdown":"# Test"}' https://aeoforged.com/api/v1/score. 4. See the Prompting Guide or MCP Setup for agent wiring.

Hard rules for agents

  • Grounding gate. Research first. POST /write returns 422 research_required without research sources. Submit-for-review and final: true saves return 422 ungrounded_content without research-allow-listed citations. Prefer POST /api/v1/create if you want one grounded call.
  • Score bar. submit-for-review rejects scores below 80 (422 below_score_bar). Improve with /improve mode to-score, or escalate via /decisions then resubmit with human-authorized acknowledge_low_score. This is an agent workflow gate — not a citation promise.
  • Human gates. When gate-status or decisions returns wait, stop. Payment and package checkout are human-only.
  • Citation honesty. /visibility and /share-of-voice are Brave-search proxies. Measured engine citations live on /visibility/scoreboard and /citation-sources.
  • Async tools. Long runners ( diagnose / complete-audit, visibility / share-of-voice, research, study run) return 202 + poll_url. Poll GET /api/v1/tool-runs/{id} until status: "complete".

Base URL: https://aeoforged.com

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

Auth: Account key aeo_sk_ or project handoff aeo_ho_. Handoff tokens are workspace-scoped; account-level listings may return handoff_scope.

Response headers: X-Credits-Charged, X-Credits-Remaining, X-Tool-Run-Id, X-AEO-Score, 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/422) and tool errors (500) do not consume credits. Authoritative balance: GET /api/v1/me.

Export & CSV: Many reads accept ?format=csv. Full per-client JSON export requires the Agency full-export capability.

Error response shape

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

Codes

  • unauthorized (401) — missing or invalid credential
  • invalid_input / invalid_json (400) — bad request body
  • research_required / ungrounded_content / below_score_bar (422) — grounding or score gate
  • insufficient_credits (402) — buy credits or upgrade
  • rate_limited (429) — see retry_after_seconds
  • handoff_scope (403) — handoff token outside its Project
  • tool_error (500) — upstream failure (no charge)

Consolidated verbs (recommended)

Prefer these intent-driven endpoints. Granular tools remain stable aliases. Live verb metadata is on GET /api/v1/onboard.

Consolidated AEOForged REST verbs with credit cost and purpose.
MethodEndpointCreditsPurpose
POST/api/v1/create20/~44 crUnified grounded creation: research → outline → write → polish → fact-check → score → package.
POST/api/v1/improve2-8 crCitation-safe transforms by mode: voice (2), to-score (2), humanize (2), aeo (8), freshness (8).
POST/api/v1/packageFree/3 crMachine-readable artifacts: jsonld (free), snippets (free), llms-txt (3).
POST/api/v1/diagnoseFreeSite-wide audit: discover pages, score each, competitive context, action plan.
POST/api/v1/factcheckFreeDeterministic statistical grounding against research sources (no LLM).
POST/api/v1/visibility10 crBrave-search visibility proxy vs competitors — report as likely visibility, not confirmed ChatGPT/Perplexity/Gemini citations.

Endpoint guide

Representative endpoints (55 below). For the complete live catalog — including every mode and credit cost — use GET /api/v1/onboard.

AEOForged REST API endpoints with HTTP method, path, credit cost, and purpose.
MethodEndpointCreditsPurpose
GET/api/v1/onboardFreeAgent bootstrap: live tool catalog, consolidated verbs, scoring dimensions, grounding/score-bar rules, and session context (account key vs handoff).
GET/api/v1/meFreeWhoami: auth type, tier, credit balance, and per-tool cost table (tool_costs).
GET/api/v1/tool-runs/[id]FreePoll long-running tools.
GET/api/v1/handoff/[token]FreeResolve a short-lived project handoff token (aeo_ho_…).
POST/api/v1/scoreFreeScore markdown or a live url across 8 AEO dimensions (0–100).
POST/api/v1/schemaFreeGenerate JSON-LD (Article / FAQPage / HowTo as applicable) from title + outline or finished content.
POST/api/v1/research10/15 crLive web research.
POST/api/v1/outline3 crGenerate a structured content outline from research data.
POST/api/v1/write8 crHosted section writing from outline + research.
POST/api/v1/polish2 crStyle and cleanup pass with changelog, heading preservation, and brand voice.
POST/api/v1/verify2 crLLM review of non-statistical claims.
POST/api/v1/factcheckFreeDeterministic grounding check for statistical claims (no LLM).
POST/api/v1/create20/~44 crConsolidated create verb (recommended).
POST/api/v1/improve2-8 crConsolidated improve verb.
POST/api/v1/packageFree/3Consolidated package verb.
POST/api/v1/generate12/20 crLegacy full pipeline.
POST/api/v1/projects/importFreeImport external markdown or a live url into a workspace as a baseline-scored content-mode article.
POST/api/v1/projects/[id]/submit-for-reviewFreeHuman review gate.
GET/api/v1/projects/[id]/gate-statusFreePoll the review gate.
POST/api/v1/decisionsFreeDurable human decision gate (MCP: aeo_ask_human).
POST/api/v1/audit5 crFetch a URL, score it, and return a prioritized improvement plan.
POST/api/v1/diagnoseFreeSite-wide diagnose (recommended alias of complete_audit workflows).
POST/api/v1/complete-auditFree*Comprehensive site audit (also MCP aeo_complete_audit).
GET/api/v1/audit-snapshots/[id]FreeRead a persisted audit snapshot (scorecards, sampling, site plan when present).
POST/api/v1/verify-pageFreeRe-fetch one URL, re-score against the snapshot's pinned research, run deterministic checks.
PATCH/api/v1/action-items/[id]FreeAction-queue transitions: open → in_progress → done | blocked (+ blocked_reason) | reopen.
POST/api/v1/action-items/[id]/document-fixFreeCapture a Remediation Story (problem + fix) in the agent's own words.
POST/api/v1/compare3 crCompare two articles head-to-head across all 8 AEO dimensions.
POST/api/v1/refresh8 crAnalyze existing content against fresh research.
POST/api/v1/cluster5 crGroup keywords by semantic similarity with pillar/supporting hierarchy and a content calendar.
POST/api/v1/extractFreeReformat markdown for featured snippet / knowledge panel / PAA extraction.
POST/api/v1/authority0-8* crAuthority OS modes: audit, blueprint, distribution_candidates, distribution, entity, external, recognition, compare, remediate, replan, social_scan, wikidata_draft, nap_scan.
POST/api/v1/study8* crOriginal Research Engine lifecycle: design (8cr) → run (lane-priced) → draft (8cr) → register (free, live HEAD verify).
POST/api/v1/citation-sourcesFreeCitation Source Intelligence over measured visibility checks (not the Brave proxy): source leaderboard, competitor fuel, off-site opportunities.
POST/api/v1/crawler-logsFreeAI crawler log analytics: upload Apache/Nginx combined or JSON lines (≤5 MB).
POST/api/v1/agent-readyFreeProbe-based agent readiness: agent user-agents, form operability, commerce schema, protocol signals, capability scores.
POST/api/v1/agent-policy3 crGenerate robots.txt agent allow rules + AGENT-POLICY.md draft.
POST/api/v1/client-profile5 crBuild client intelligence from a website (brand voice, facts, audience).
POST/api/v1/optimise8 crPage-level section analysis, intent classification, and AEO-oriented rewrites.
POST/api/v1/trackFreeRegister a URL for visibility monitoring via a Brave-search ranking proxy — not a measured ChatGPT/Perplexity/Gemini citation.
GET/api/v1/track/statusFreeList tracked URLs with latest proxy monitoring data.
GET/api/v1/visibility/scoreboardFreeQuery-first measured citation scoreboard (real engine checks): per-query status, SOV basis, winning page, competitors cited.
GET/api/v1/sovFreePersisted Share of Voice history — Brave-search proxy (not confirmed AI-engine citations).
POST/api/v1/crawlabilityFreeAI crawlability: robots.txt for AI bots, meta directives, llms.txt, sitemap, JS rendering signals.
POST/api/v1/llms-txt3 crGenerate spec-compliant llms.txt + llms-full.txt with semantic page grouping and deployment instructions.
POST/api/v1/share-of-voice10 crShare of Voice tracker (Brave proxy).
POST/api/v1/moat-check15 crCompetitive gap analysis: topic/format/schema/depth gaps and a prioritized action plan.
GET/api/v1/projectsFreeList articles — org-scoped for API keys, workspace-scoped for handoff tokens.
GET/api/v1/workspacesFreeList accessible Projects (workspaces).
POST/api/v1/workflow/audit-improve5-13 crComposite: audit a URL then refresh if below threshold.
POST/api/v1/workflow/strategy~44 crComposite: cluster → research + outline top N pillars.
POST/api/v1/workflow/health5/URL crBatch-audit up to 10 URLs into a priority dashboard.
POST/api/v1/workflow/quality-gateFreeScore against a target threshold with pass/fail + fixes.
GET/api/v1/platform/statsFreePublic aggregate platform analytics (no auth).
GET/api/v1/clients/[workspaceId]/exportFreeAgency full-export JSON archive for one client (profile, latest snapshot, action items, tracked URLs, visibility).
FreeGET

/api/v1/onboard

Agent bootstrap: live tool catalog, consolidated verbs, scoring dimensions, grounding/score-bar rules, and session context (account key vs handoff). Call this first — costs and tool lists here stay current.

Request Body

(no body — optional ?workspace_id= for setup_checklist)

Response

{
  "ok": true,
  "data": {
    "tools": [ { "name": "research", "endpoint": "POST /api/v1/research", "cost": 10, "..." : "..." } ],
    "verbs": [ { "name": "create", "endpoint": "POST /api/v1/create", "mcp": "aeo_create", "..." : "..." } ],
    "workflow": {
      "grounding_gate": "RESEARCH FIRST — enforced...",
      "score_bar": "submit-for-review enforces score >= 80..."
    },
    "session_context": { "mode": "account" }
  }
}
FreeGET

/api/v1/me

Whoami: auth type, tier, credit balance, and per-tool cost table (tool_costs). Call before paid tools to verify auth and budget. Prefer this over any static cost table in docs.

Request Body

(no body)

Response

{
  "ok": true,
  "data": {
    "user_id": "uuid",
    "auth_type": "api_key",
    "tier": "pro",
    "credits": {
      "included_remaining": 187,
      "balance": 0,
      "total": 187
    },
    "tool_costs": {
      "score": 0,
      "research": 10,
      "research_deep": 15,
      "write_sections": 8,
      "create": 20,
      "study_design": 8,
      "moat_check": 15
    }
  },
  "credits_remaining": 187
}
FreeGET

/api/v1/tool-runs/[id]

Poll long-running tools. Async tools return 202 with run_id + poll_url. Statuses: running | complete | error | timeout. Check likely_stalled when heartbeat is old.

Request Body

(no body)

Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "status": "complete",
    "step": "aggregating_results",
    "progress": { "current": 10, "total": 10 },
    "result": { "..." : "..." },
    "heartbeat_ago_seconds": 2,
    "likely_stalled": false
  }
}
FreeGET

/api/v1/handoff/[token]

Resolve a short-lived project handoff token (aeo_ho_…). Returns workspace brief, articles, credits, MCP/REST config, next steps, and (when present) audit queue + verify-page instructions. Then use the same token as Bearer.

Request Body

(token in path — no body)

Response

{
  "ok": true,
  "data": {
    "workspace": { "id": "uuid", "name": "..." },
    "credits": { "total": 187 },
    "mcp": { "url": "https://aeoforged.com/api/mcp/mcp" },
    "next_steps": [ "..." ]
  }
}
FreePOST

/api/v1/score

Score markdown or a live url across 8 AEO dimensions (0–100). Page-type aware. Pass research for entity/grounding feedback. Scoring is publish-readiness feedback — not a live citation guarantee.

Request Body

{
  "markdown": "# Your Article\n\nContent here...",
  "hasJsonLd": false,
  "entities": ["entity1", "entity2"]
  // or: "url": "https://example.com/page"
}

Response

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

/api/v1/schema

Generate JSON-LD (Article / FAQPage / HowTo as applicable) from title + outline or finished content.

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", "..." : "..." }
    ]
  }
}
10/15 creditsPOST

/api/v1/research

Live web research. Standard (10cr) or deep (15cr). Async by default (202 + poll_url); force blocking with ?wait=true. Pass a detailed brief for better results.

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": ["https://..."]
  },
  "credits_remaining": 190
}
3 creditsPOST

/api/v1/outline

Generate a structured content outline from research data. Optional project_id persists to the workspace article.

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

/api/v1/write

Hosted section writing from outline + research. Requires research-backed sources (422 research_required otherwise). Citations outside the research allow-list are stripped.

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": "..." }]
  }
}
2 creditsPOST

/api/v1/polish

Style and cleanup pass with changelog, heading preservation, and brand voice. Prefer POST /api/v1/improve?mode=voice for new integrations.

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

/api/v1/verify

LLM review of non-statistical claims. For statistics, prefer /api/v1/factcheck (deterministic, free).

Request Body

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

Response

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

/api/v1/factcheck

Deterministic grounding check for statistical claims (no LLM). Pass research, or project_id to load pinned research_json. /score can return grounding when research is supplied.

Request Body

{
  "markdown": "Article content with 70% stats...",
  "research": { "..." : "..." }
  // or: "project_id": "<uuid>"
}

Response

{
  "ok": true,
  "data": {
    "claims": [ { "text": "...", "status": "supported", "matchedSourceUrl": "https://..." } ],
    "totalClaims": 3,
    "supportedClaims": 2,
    "unsupportedClaims": ["..."],
    "groundingScore": 67
  }
}
20/~44 creditsPOST

/api/v1/create

Consolidated create verb (recommended). Modes single/gate (~20cr) or strategy (~44cr). Grounds end-to-end so lightweight agents need not chain research → write → factcheck manually.

Request Body

{
  "mode": "single",
  "keyword": "answer engine optimization",
  "brief": "Audience, product, CTA",
  "target_score": 80
}

Response

{
  "ok": true,
  "data": {
    "markdown": "# ...",
    "score": { "total": 82 },
    "project_id": "uuid"
  }
}
2-8 creditsPOST

/api/v1/improve

Consolidated improve verb. Modes: voice | aeo | to-score | freshness | humanize. Cost depends on mode (see /me or /onboard).

Request Body

{
  "mode": "to-score",
  "markdown": "# Draft...",
  "research": { "..." : "..." },
  "target_score": 80
}

Response

{
  "ok": true,
  "data": {
    "markdown": "# Revised...",
    "score": { "total": 81 }
  }
}
Free/3POST

/api/v1/package

Consolidated package verb. Modes: jsonld | snippets | llms-txt.

Request Body

{
  "mode": "jsonld",
  "markdown": "# Finished article...",
  "title": "Article title"
}

Response

{
  "ok": true,
  "data": {
    "schemas": ["..."]
  }
}
12/20 creditsPOST

/api/v1/generate

Legacy full pipeline. Draft (12cr) or publish (20cr). New integrations should prefer /api/v1/create.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "markdown": "# Article Title\n\n...",
    "score": { "total": 85 },
    "completedSteps": ["research", "outline", "write", "polish", "verify", "score"]
  }
}
FreePOST

/api/v1/projects/import

Import external markdown or a live url into a workspace as a baseline-scored content-mode article. Then research → score → improve(to-score) → save. Ungrounded until research-backed citations are added.

Request Body

{
  "workspace_id": "uuid",
  "markdown": "# Existing article...",
  "keyword": "optional topic"
  // or: "url": "https://example.com/article"
}

Response

{
  "ok": true,
  "data": {
    "project_id": "uuid",
    "baseline": { "total": 58 },
    "weakest_dimensions": ["Direct Answer", "Schema"],
    "next_steps": ["research", "score", "improve"]
  }
}
FreePOST

/api/v1/projects/[id]/submit-for-review

Human review gate. Rejects ungrounded content (422 ungrounded_content) and scores below 80 (422 below_score_bar) unless a human-authorized acknowledge_low_score + reason is present. Poll gate-status afterward; wait means stop.

Request Body

{
  // optional escape after aeo_ask_human:
  "acknowledge_low_score": true,
  "reason": "Human approved shipping at 76"
}

Response

{
  "ok": true,
  "data": {
    "status": "pending_review",
    "project_id": "uuid"
  }
}
FreeGET

/api/v1/projects/[id]/gate-status

Poll the review gate. action: wait | apply_feedback_and_resubmit | publish_and_track. Never skip wait.

Request Body

(no body)

Response

{
  "ok": true,
  "data": {
    "action": "wait",
    "status": "pending_review"
  }
}
FreePOST

/api/v1/decisions

Durable human decision gate (MCP: aeo_ask_human). Create a question (+ optional options), then GET /api/v1/decisions/{id} until action is proceed. Wait means stop. Payment and package checkout are always human-only — never automate them.

Request Body

{
  "question": "Ship this draft below score 80?",
  "options": ["Yes, acknowledge low score", "Keep iterating"]
}

Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "status": "pending",
    "action": "wait"
  }
}
5 creditsPOST

/api/v1/audit

Fetch a URL, score it, and return a prioritized improvement plan. Also available as the consolidated audit verb with crawlability + grounding extras.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "url": "https://example.com/article",
    "score": { "total": 62, "breakdown": ["..."] },
    "improvements": [
      { "priority": "high", "category": "Structure", "description": "Add question-format H2 headings" }
    ]
  }
}
FreePOST

/api/v1/diagnose

Site-wide diagnose (recommended alias of complete_audit workflows). Async by default → 202 + poll_url. Free path is bounded; paid depth flags (when authorized) are priced in code and returned by the API — never invent prices.

Request Body

{
  "siteUrl": "https://example.com",
  "workspace_id": "uuid"
}

Response

{
  "ok": true,
  "data": {
    "run_id": "uuid",
    "poll_url": "/api/v1/tool-runs/uuid",
    "status": "running"
  }
}
Free*POST

/api/v1/complete-audit

Comprehensive site audit (also MCP aeo_complete_audit). Discovers pages, scores, optional competitor context, persists an audit snapshot + action items. Async by default. Pass workspace_id when available.

Request Body

{
  "siteUrl": "https://example.com",
  "workspace_id": "uuid"
}

Response

{
  "ok": true,
  "data": {
    "run_id": "uuid",
    "poll_url": "/api/v1/tool-runs/uuid"
  }
}
FreeGET

/api/v1/audit-snapshots/[id]

Read a persisted audit snapshot (scorecards, sampling, site plan when present). Org-scoped; handoff tokens limited to their workspace. ?format=csv&dataset=scorecards|actions for CSV.

Request Body

(no body)

Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "siteUrl": "https://example.com",
    "sampling": { "discovered": 40, "technicalChecked": 40, "llmAudited": 30, "strategy": "scored-select" },
    "report": { "overallScore": 71, "scorecards": ["..."] }
  }
}
FreePOST

/api/v1/verify-page

Re-fetch one URL, re-score against the snapshot's pinned research, run deterministic checks. Sole writer that can promote done/applied items to verified. MCP: aeo_verify_page.

Request Body

{
  "url": "https://example.com/pricing",
  "snapshot_id": "uuid"
}

Response

{
  "ok": true,
  "data": {
    "url": "https://example.com/pricing",
    "baselineScore": 62,
    "freshScore": 78,
    "promoted": ["action-item-uuid"]
  }
}
FreePATCH

/api/v1/action-items/[id]

Action-queue transitions: open → in_progress → done | blocked (+ blocked_reason) | reopen. Rejects status verified — use verify-page. MCP: aeo_action_update.

Request Body

{
  "status": "in_progress"
}

Response

{
  "ok": true,
  "data": { "id": "uuid", "status": "in_progress" }
}
FreePOST

/api/v1/action-items/[id]/document-fix

Capture a Remediation Story (problem + fix) in the agent's own words. No LLM. Measured impact is attached later from verify-page evidence. MCP: aeo_document_fix.

Request Body

{
  "problem": "Homepage had no FAQ block answer engines could extract.",
  "fix": "Added a concise FAQ section with schema matching visible copy."
}

Response

{
  "ok": true,
  "data": { "action_item_id": "uuid", "recorded": true }
}
3 creditsPOST

/api/v1/compare

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",
    "recommendations": ["..."]
  }
}
8 creditsPOST

/api/v1/refresh

Analyze existing content against fresh research. Prefer /api/v1/improve mode freshness for new integrations.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "currentScore": { "total": 55 },
    "projectedScore": 72,
    "updatePlan": ["..."]
  }
}
5 creditsPOST

/api/v1/cluster

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

Request Body

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

Response

{
  "ok": true,
  "data": {
    "clusters": ["..."],
    "contentCalendar": ["..."]
  }
}
FreePOST

/api/v1/extract

Reformat markdown for featured snippet / knowledge panel / PAA extraction. Prefer /api/v1/package mode snippets for new integrations.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "featuredSnippet": { "definition": "..." },
    "peopleAlsoAsk": ["..."],
    "extractabilityScore": 8
  }
}
0-8* creditsPOST

/api/v1/authority

Authority OS modes: audit, blueprint, distribution_candidates, distribution, entity, external, recognition, compare, remediate, replan, social_scan, wikidata_draft, nap_scan. Costs vary by mode — read /onboard or /me. MCP: aeo_authority.

Request Body

{
  "mode": "audit",
  "workspace_id": "uuid"
}

Response

{
  "ok": true,
  "data": {
    "mode": "audit",
    "authorityProfile": { "..." : "..." }
  }
}
8* creditsPOST

/api/v1/study

Original Research Engine lifecycle: design (8cr) → run (lane-priced) → draft (8cr) → register (free, live HEAD verify). Lanes: bench | engine | first_party | comparison. Depth floors refuse thin samples. MCP: aeo_study. Exact run pricing from /me and the API response.

Request Body

{
  "mode": "design",
  "lane": "engine",
  "workspace_id": "uuid",
  "question": "Which domains are cited for category queries?"
}

Response

{
  "ok": true,
  "data": {
    "study_id": "uuid",
    "status": "designed"
  }
}
FreePOST

/api/v1/citation-sources

Citation Source Intelligence over measured visibility checks (not the Brave proxy): source leaderboard, competitor fuel, off-site opportunities. Run visibility checks first. MCP: aeo_citation_sources.

Request Body

{
  "workspace_id": "uuid"
}

Response

{
  "ok": true,
  "data": {
    "sources": ["..."],
    "opportunities": ["..."]
  }
}
FreePOST

/api/v1/crawler-logs

AI crawler log analytics: upload Apache/Nginx combined or JSON lines (≤5 MB). Deterministic parse — bots seen, top pages, error hotspots, crawl-vs-citation cross-ref. Sample-scoped honesty (never claim a bot never visits beyond the sample). MCP: aeo_crawler_logs.

Request Body

{
  "log": "127.0.0.1 - - [08/Aug/2026:12:00:00 +0000] \"GET / HTTP/1.1\" 200 1234 \"-\" \"GPTBot/...\"",
  "workspace_id": "uuid",
  "site_url": "https://example.com"
}

Response

{
  "ok": true,
  "data": {
    "botsSeen": ["GPTBot"],
    "findings": ["..."]
  }
}
FreePOST

/api/v1/agent-ready

Probe-based agent readiness: agent user-agents, form operability, commerce schema, protocol signals, capability scores. MCP: aeo_agent_ready.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "capabilities": { "read": "pass", "forms": "partial" },
    "recommendations": ["..."]
  }
}
3 creditsPOST

/api/v1/agent-policy

Generate robots.txt agent allow rules + AGENT-POLICY.md draft. MCP: aeo_agent_policy.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "robotsRules": "...",
    "agentPolicyMd": "..."
  }
}
5 creditsPOST

/api/v1/client-profile

Build client intelligence from a website (brand voice, facts, audience). List existing profiles via GET /api/v1/client-profile/list.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "company_name": "Example",
    "profile": { "..." : "..." }
  }
}
8 creditsPOST

/api/v1/optimise

Page-level section analysis, intent classification, and AEO-oriented rewrites. Prefer /api/v1/improve mode aeo for new integrations.

Request Body

{
  "url": "https://example.com/page"
}

Response

{
  "ok": true,
  "data": {
    "sections": ["..."],
    "rewrites": ["..."]
  }
}
FreePOST

/api/v1/track

Register a URL for visibility monitoring via a Brave-search ranking proxy — not a measured ChatGPT/Perplexity/Gemini citation. For measured engine citations use /api/v1/visibility/scoreboard.

Request Body

{
  "url": "https://example.com/my-article",
  "keyword": "answer engine optimization",
  "project_id": "uuid"
}

Response

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

/api/v1/track/status

List tracked URLs with latest proxy monitoring data. Supports ?format=csv.

Request Body

(no body)

Response

{
  "ok": true,
  "data": [
    {
      "id": "uuid",
      "url": "https://example.com/my-article",
      "keyword": "answer engine optimization",
      "status": "active"
    }
  ]
}
FreeGET

/api/v1/visibility/scoreboard

Query-first measured citation scoreboard (real engine checks): per-query status, SOV basis, winning page, competitors cited. ?workspace_id= to scope, ?format=csv to export.

Request Body

(no body — query params: ?workspace_id=uuid, ?format=csv)

Response

{
  "ok": true,
  "data": {
    "summary": {
      "citedRate": 0.42,
      "perQuery": [
        { "query": "best aeo tools", "status": "cited", "bestTier": "page", "winningPage": "https://example.com/tools" }
      ]
    },
    "measuredEngines": ["perplexity", "chatgpt"]
  }
}
FreeGET

/api/v1/sov

Persisted Share of Voice history — Brave-search proxy (not confirmed AI-engine citations). Org-scoped; not available to handoff tokens. ?format=csv supported.

Request Body

(no body — query param: ?format=csv)

Response

{
  "ok": true,
  "data": {
    "methodology": "Brave-search visibility proxy (not a confirmed AI-engine citation).",
    "snapshots": ["..."],
    "count": 1
  }
}
FreePOST

/api/v1/crawlability

AI crawlability: robots.txt for AI bots, meta directives, llms.txt, sitemap, JS rendering signals.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "siteUrl": "https://example.com",
    "checkedAt": "2026-08-08T12:00:00Z",
    "overallStatus": "partial",
    "recommendations": ["..."]
  }
}
3 creditsPOST

/api/v1/llms-txt

Generate spec-compliant llms.txt + llms-full.txt with semantic page grouping and deployment instructions.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "llmsTxt": "# example.com\n...",
    "llmsFullTxt": "# example.com\n...",
    "deploymentInstructions": "..."
  }
}
10 creditsPOST

/api/v1/share-of-voice

Share of Voice tracker (Brave proxy). Prefer /api/v1/visibility for the consolidated verb. Async by default. Not the same as measured scoreboard citations.

Request Body

{
  "keywords": ["aeo optimization"],
  "clientDomain": "example.com",
  "competitorDomains": ["competitor1.com"]
}

Response

{
  "ok": true,
  "data": {
    "domains": ["..."],
    "gaps": ["..."],
    "summary": "..."
  }
}
15 creditsPOST

/api/v1/moat-check

Competitive gap analysis: topic/format/schema/depth gaps and a prioritized action plan. MCP: aeo_moat_check.

Request Body

{
  "siteUrl": "https://example.com",
  "competitorUrls": ["https://competitor.com"]
}

Response

{
  "ok": true,
  "data": {
    "gaps": ["..."],
    "actionPlan": ["..."]
  }
}
FreeGET

/api/v1/projects

List articles — org-scoped for API keys, workspace-scoped for handoff tokens. Optional ?workspace_id=.

Request Body

(no body — query param: ?workspace_id=uuid)

Response

{
  "ok": true,
  "data": {
    "projects": [
      {
        "id": "uuid",
        "name": "Answer engine optimization guide",
        "pipeline_status": "scored",
        "updated_at": "2026-08-08T12:00:00Z"
      }
    ],
    "count": 1
  }
}
FreeGET

/api/v1/workspaces

List accessible Projects (workspaces). Handoff tokens see only their bound Project.

Request Body

(no body)

Response

{
  "ok": true,
  "data": {
    "workspaces": [
      { "id": "uuid", "name": "Acme content", "status": "active" }
    ]
  }
}
5-13 creditsPOST

/api/v1/workflow/audit-improve

Composite: audit a URL then refresh if below threshold. Prefer /diagnose or /improve for new work.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "audit": { "..." : "..." },
    "refresh": { "..." : "..." },
    "totalCreditsUsed": 13
  }
}
~44 creditsPOST

/api/v1/workflow/strategy

Composite: cluster → research + outline top N pillars. Prefer /api/v1/create mode strategy.

Request Body

{
  "keywords": ["what is SEO", "SEO basics"],
  "domain": "example.com",
  "researchTopN": 3
}

Response

{
  "ok": true,
  "data": {
    "clusters": ["..."],
    "pillars": ["..."],
    "totalCreditsUsed": 44
  }
}
5/URL creditsPOST

/api/v1/workflow/health

Batch-audit up to 10 URLs into a priority dashboard. Prefer /diagnose for site-wide work.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "results": ["..."],
    "averageScore": 58,
    "totalCreditsUsed": 10
  }
}
FreePOST

/api/v1/workflow/quality-gate

Score against a target threshold with pass/fail + fixes. Prefer /api/v1/create mode gate or free /score loops.

Request Body

{
  "markdown": "# Your Article\n\nContent here...",
  "targetScore": 80
}

Response

{
  "ok": true,
  "data": {
    "passed": false,
    "score": { "total": 68 },
    "targetScore": 80,
    "fixes": ["..."]
  }
}
FreeGET

/api/v1/platform/stats

Public aggregate platform analytics (no auth). Figures are measured aggregates when available — not a guarantee for your site. Prefer your own scoreboard for client claims.

Request Body

(no body — no auth required)

Response

{
  "success": true,
  "data": {
    "stats": {
      "stat_date": "2026-08-08",
      "total_tracked": 142,
      "avg_score_cited": 84.2,
      "computed_at": "2026-08-08T08:00:00Z"
    }
  }
}
FreeGET

/api/v1/clients/[workspaceId]/export

Agency full-export JSON archive for one client (profile, latest snapshot, action items, tracked URLs, visibility). Capability-gated; not available to handoff tokens.

Request Body

(no body — returns a JSON file attachment)

Response

{
  "exportedAt": "2026-08-08T08:00:00Z",
  "workspace": { "id": "uuid", "name": "Acme" },
  "latestSnapshot": { "id": "uuid" },
  "actionItems": ["..."],
  "visibility": { "citedRate": 0.4 }
}

Sample timestamps on this page use 2026-08-08. Credit costs marked with * vary by mode or depth — always confirm with GET /api/v1/me.