AEOForged
Get in touch

REST API Reference

The AEOForged REST API is an HTTPS, JSON API that gives developers and AI agents programmatic access to all 25+ AEO tools — scoring, research, content generation, auditing, comparison, crawlability, citation monitoring, and competitive intelligence — across the full content lifecycle. Every endpoint is authenticated with a Bearer API key and returns a consistent{ ok, data } envelope.

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

Last updated

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.

Export & CSV: Read endpoints are org-scoped — any teammate in the organization can pull data with an org API key, not just the owner. Audit snapshots, monitoring (status / history / evidence), the visibility scoreboard, and SOV history accept ?format=csv for a downloadable attachment. Full per-client JSON bundles (/api/v1/clients/[workspaceId]/export) require 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 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)

Endpoint summary

All 34 endpoints at a glance — method, path, credit cost, and purpose.

AEOForged REST API endpoints with HTTP method, path, credit cost, and purpose.
MethodEndpointCreditsPurpose
GET/api/v1/meFreeWhoami: returns auth type, tier, credit balance, and per-tool cost table.
POST/api/v1/scoreFreeScore markdown content for AEO readiness across all 8 dimensions, returning an overall 0–100 total plus per-dimension breakdown and prioritised suggestions.
POST/api/v1/schemaFreeGenerate valid JSON-LD structured data (Article and FAQPage) from a title and outline so answer engines get machine-readable context for the page.
POST/api/v1/research10/15 crRun live web research.
POST/api/v1/outline3 crGenerate a structured content outline from research data.
POST/api/v1/write8 crWrite full article sections from outline and research, with verified citations, tone/voice control, and coherence pass.
POST/api/v1/polish2 crStyle and cleanup pass with changelog, heading preservation, brand voice, and idempotency guard.
POST/api/v1/verify2 crLLM-judged review of NON-statistical claims (qualitative/entity).
POST/api/v1/factcheckFreeDeterministic grounding check for statistical claims (no LLM).
POST/api/v1/generate12/20 crRun the full pipeline.
POST/api/v1/audit5 crFetch a URL, score it for AEO readiness, and get a prioritized improvement plan.
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.
POST/api/v1/extractFreeReformat markdown for answer engine extraction.
POST/api/v1/trackFreeRegister a URL for citation monitoring across Brave, Google AI, and Perplexity.
GET/api/v1/track/statusFreeGet all tracked URLs with current monitoring data including latest citation status, position, and score.
GET/api/v1/track/[id]/historyFreeGet check history for a specific tracked URL.
GET/api/v1/alertsFreeGet unread alerts.
POST/api/v1/alerts/readFreeMark one or more alerts as read.
GET/api/v1/platform/statsFreeLatest platform analytics — tracked pages, measured page-tier citation counts, average publish scores.
GET/api/v1/case-studiesFreeGet opt-in case studies showcasing before/after AEO scores and citation outcomes.
POST/api/v1/case-studies/opt-inFreeToggle case study opt-in for a tracked URL.
POST/api/v1/workflow/audit-improve5-13 crWorkflow: audits a URL then generates a refresh plan if score is below threshold.
POST/api/v1/workflow/strategy~44 crWorkflow: clusters keywords, then researches and outlines the top N pillar topics.
POST/api/v1/workflow/health5/URL crWorkflow: batch-audit up to 10 URLs and return a sorted priority dashboard with per-URL scores and improvement plans.
POST/api/v1/workflow/quality-gateFreeWorkflow: score content against a target threshold.
POST/api/v1/crawlabilityFreeAI Crawlability Check: analyse a website for AI bot access.
POST/api/v1/llms-txt3 crGenerate spec-compliant llms.txt and llms-full.txt files for a website.
POST/api/v1/share-of-voice10 crShare of Voice tracker: measure AI answer visibility across Brave, Google AI, and Perplexity.
GET/api/v1/projectsFreeList articles your account can access — org-scoped for teammates (any member, not just the owner), workspace-scoped for handoff tokens.
GET/api/v1/visibility/scoreboardFreeQuery-first measured citation scoreboard for your org/workspace: per-query citation status (measured), share-of-voice, winning page, and competitors cited.
GET/api/v1/sovFreePersisted Share of Voice history — the Brave-search visibility proxy (not a confirmed AI-engine citation; for measured citations use /api/v1/visibility/scoreboard).
GET/api/v1/clients/[workspaceId]/exportFreeAgency full-export: a single JSON archive for one client — profile, latest audit snapshot, action items, tracked URLs, and measured visibility summary.
FreeGET

/api/v1/me

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

/api/v1/score

Score markdown content for AEO readiness across all 8 dimensions, returning an overall 0–100 total plus per-dimension breakdown and prioritised suggestions.

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

/api/v1/schema

Generate valid JSON-LD structured data (Article and FAQPage) from a title and outline so answer engines get machine-readable context for the page.

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

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

/api/v1/outline

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

/api/v1/write

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

/api/v1/polish

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

/api/v1/verify

LLM-judged review of NON-statistical claims (qualitative/entity). For statistics, prefer /api/v1/factcheck (deterministic, free). Returns confidence tiers + verification report.

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 a project_id to load pinned research_json. /score also returns this as `grounding` (X-AEO-Grounding-Score header) 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
  }
}
12/20 creditsPOST

/api/v1/generate

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"]
  }
}
5 creditsPOST

/api/v1/audit

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": [...]
  }
}
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",
    "dimensionComparison": [
      { "category": "Structure", "scoreA": 21, "scoreB": 12, "winner": "A", "insight": "..." }
    ],
    "summary": "Content A significantly outperforms...",
    "aStrengths": [...],
    "bStrengths": [...],
    "recommendations": [...]
  }
}
8 creditsPOST

/api/v1/refresh

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

/api/v1/cluster

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

/api/v1/extract

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": [...]
  }
}
FreePOST

/api/v1/track

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

/api/v1/track/status

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"
    }
  ]
}
FreeGET

/api/v1/track/[id]/history

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

/api/v1/alerts

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

/api/v1/alerts/read

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

/api/v1/platform/stats

Latest platform analytics — tracked pages, measured page-tier citation counts, average publish scores. Public endpoint, no auth required. Dogfood-owned URLs are excluded from aggregates.

Request Body

(no body — no auth required)

Response

{
  "success": true,
  "data": {
    "stats": {
      "stat_date": "2026-06-19",
      "total_tracked": 142,
      "total_cited": 38,
      "citation_rate": 26.76,
      "avg_score_cited": 84.2,
      "avg_score_not_cited": 61.5,
      "avg_time_to_citation_hours": 168,
      "articles_above_80": 67,
      "articles_above_80_cited_rate": 41.79,
      "computed_at": "2026-06-19T08:00:00Z"
    },
    "cohort": "proof",
    "proof": {
      "citationRateHigh": "41.79% of content scoring 80+ has a measured page-tier citation ...",
      "avgTimeToCitation": "Average time to first measured page citation: 7 days",
      "totalPages": "142 pages tracked in our proof portfolio"
    }
  }
}
FreeGET

/api/v1/case-studies

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"
    }
  ]
}
FreePOST

/api/v1/case-studies/opt-in

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 }
}
5-13 creditsPOST

/api/v1/workflow/audit-improve

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
}
~44 creditsPOST

/api/v1/workflow/strategy

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
}
5/URL creditsPOST

/api/v1/workflow/health

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

/api/v1/workflow/quality-gate

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

/api/v1/crawlability

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

/api/v1/llms-txt

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

/api/v1/share-of-voice

Share of Voice tracker: measure AI answer visibility across Brave, Google AI, and Perplexity. Compares client domain vs up to 5 competitors for up to 20 keywords.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "clientDomain": "example.com",
    "competitorDomains": ["competitor1.com", "competitor2.com"],
    "keywords": ["aeo optimization", "answer engine content"],
    "totalQueries": 6,
    "domains": [
      { "domain": "example.com", "isClient": true, "mentions": 3, "sov": 50, "coverage": 100, "avgPosition": 2.1 }
    ],
    "perKeyword": [...],
    "gaps": [{ "keyword": "...", "visibleCompetitors": [...] }],
    "dominations": [{ "keyword": "...", "position": 1 }],
    "summary": "..."
  },
  "credits_charged": 10,
  "credits_remaining": 90
}
FreeGET

/api/v1/projects

List articles your account can access — org-scoped for teammates (any member, not just the owner), workspace-scoped for handoff tokens. Optional ?workspace_id= filter.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "projects": [
      {
        "id": "uuid",
        "name": "Answer engine optimization guide",
        "seed_keyword": "aeo",
        "pipeline_status": "scored",
        "published_url": "https://example.com/aeo",
        "workspace_id": "uuid",
        "updated_at": "2026-06-15T12:00:00Z"
      }
    ],
    "count": 1
  }
}
FreeGET

/api/v1/visibility/scoreboard

Query-first measured citation scoreboard for your org/workspace: per-query citation status (measured), share-of-voice, winning page, and competitors cited. Add ?format=csv for a CSV attachment, ?workspace_id= to scope to one client.

Request Body

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

Response

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

/api/v1/sov

Persisted Share of Voice history — the Brave-search visibility proxy (not a confirmed AI-engine citation; for measured citations use /api/v1/visibility/scoreboard). Org-scoped; add ?format=csv for trend export. Not available to handoff tokens.

Request Body

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

Response

{
  "ok": true,
  "data": {
    "methodology": "Brave-search visibility proxy (not a confirmed AI-engine citation).",
    "snapshots": [
      { "id": "uuid", "created_at": "2026-06-10T00:00:00Z", "client_domain": "example.com", "report_data": { "domains": [...] } }
    ],
    "count": 1
  }
}
FreeGET

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

Agency full-export: a single JSON archive for one client — profile, latest audit snapshot, action items, tracked URLs, and measured visibility summary. Gated by the Agency full-export capability; returns a downloadable attachment. Not available to handoff tokens.

Request Body

(no body — returns a JSON file attachment)

Response

{
  "exportedAt": "2026-06-16T08:00:00Z",
  "workspace": { "id": "uuid", "name": "Acme", "goal": "...", "status": "active" },
  "clientProfile": { "company_name": "Acme", "site_url": "https://acme.com", ... },
  "latestSnapshot": { "id": "uuid", "siteUrl": "https://acme.com", "report": { ... }, "researchContext": { ... } },
  "actionItems": [ ... ],
  "trackedUrls": [ ... ],
  "visibility": { "perQuery": [ ... ], "citedRate": 0.4 }
}