Pricing
Log inStart free trial→
Try free
Measure

MentionShare Tracking

See your brand mention rate across 9 AI engines daily

Competitor Intelligence

Track share-of-voice vs competitors across all engines

Prompt Performance

Per-query mention rates and 90-day trend lines

Brand Sentiment

Track if AI describes your brand positively or negatively

Optimize

Fix Generator

Generate FAQ blocks, JSON-LD schema, and answer paragraphs

AI SEO Audit

Page-by-page AI readiness scoring with specific fixes

Integrations

Connect GA4, Search Console, Slack, and your data stack

Authority Capture

Build topical authority AI engines trust and cite

Featured

Fix Generator

Generate FAQ blocks, JSON-LD schema, and answer paragraphs — ready to publish in one click.

See how it works →

IntegrationsGA4Search ConsoleSlackAPI

By Team

Marketing Teams

Track AI visibility and generate content at scale

Founders & Startups

Get cited by AI engines from day one — no SEO agency needed

Agencies

Manage client workspaces with white-label PDF reporting

B2B SaaS Companies

Win AI-generated buyer comparisons in your software category

Enterprise

SSO, dedicated support & custom contracts

How Teams Use It

Improve AI Citations

Publish content that trains ChatGPT and Perplexity to recommend you

Prove AI-Driven ROI

Connect AI citations to real traffic and pipeline via GA4

Get a Competitive Edge

Real results from teams dominating AI-generated answers

Managing multiple clients?See Agency plan →

Content

Blog

New

AEO strategies, AI visibility guides, and industry insights

What's New

Updated

Latest product releases, features, and platform updates

AEO Beginner Guide

Free

Free 10-step guide to getting cited in AI search results

Tutorials

Step-by-step video walkthroughs for every feature

Reference

Documentation

Platform guide — features, workflows, and getting started

API Reference

REST API docs, authentication, and code examples

Case Studies

Real results from marketing teams and agencies

Comparisons

TrueCite vs Otterly, Peec AI, and more

Security

Data handling, compliance, and infrastructure

New to AEO?
Read the free guide →About us →

On this page

Overview
Authentication
Base URL
Rate Limits
Endpoints
GET /mentionshareGET /scansGET /competitorsGET /fixesPOST /scansGET /scans/status/{id}GET /authorityPOST /authorityGET /authority/status/{id}GET /authority/{id}/blocksPOST /authority/{id}/regenerateGET /crawler-checkPOST /crawler-checkGET /crawler-check/status/{id}GET /llms-checkPOST /llms-checkGET /llms-check/status/{id}GET /schema-auditPOST /schema-auditGET /schema-audit/status/{id}GET /schema-audit/{id}GET /ai-seo-auditPOST /ai-seo-auditGET /ai-seo-audit/status/{id}GET /ai-seo-audit/{pageId}
Code Examples
Webhooks
Error Codes

Need help?

hello@truecite.ai

TrueCite REST API

Programmatic access to your scan data, MentionShare scores, competitor analysis, and Fix Generator content — plus the ability to trigger new scans directly from your own workflows. Available on Enterprise plans.

✓ REST API
✓ JSON responses
✓ Enterprise only

Authentication

All API requests require an API key passed in the Authorization header. Generate your key from Settings → Developer.

Authorization headercurl
curl https://truecite.ai/api/v1/mentionshare \
  -H "Authorization: Bearer tc_live_..."

⚠️ Keep your API key secret. Never expose it in client-side code or public repositories. Keys are shown only once at creation — store them in a secrets manager. Revoke a compromised key from Settings → Developer.

Base URL

Production
https://truecite.ai/api/v1

All v1 endpoints are served from truecite.ai — there is no separate API subdomain.

Rate Limits

100

requests / hour

per API key — all Enterprise keys share the same limit

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header (seconds until the window resets). The limit resets on a rolling 1-hour window, not at a fixed clock boundary.

Endpoints

GET/api/v1/mentionshareMentionShare score and per-engine breakdown (last 200 scans)

Response

200 OK
{
  "data": {
    "mention_share": 34,
    "total_scans": 150,
    "scans_with_mention": 51,
    "by_engine": {
      "chatgpt": 40,
      "perplexity": 28,
      "gemini": 35,
      "claude": 22
    },
    "business_id": "550e8400-e29b-41d4-a716-446655440000",
    "computed_at": "2026-06-13T10:00:00Z"
  }
}
GET/api/v1/scans?limit=50&offset=0Paginated scan history. limit max 100.

Response

200 OK
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ai_engine": "chatgpt",
      "prompt_used": "What is the best AEO tool for B2B SaaS?",
      "brand_mentioned": true,
      "brand_position": 2,
      "brand_sentiment": "positive",
      "mention_share_score": 45,
      "scanned_at": "2026-06-13T10:00:00Z",
      "country": "us",
      "language": null
    }
  ],
  "meta": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "business_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
GET/api/v1/competitorsCompetitors with mention count and rate (based on last 500 scans)

Response

200 OK
{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Peec AI",
      "website": "https://peec.ai",
      "mention_count": 12,
      "mention_rate": 8
    }
  ],
  "meta": {
    "total": 3,
    "scans_analyzed": 150,
    "business_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
GET/api/v1/fixes?limit=50&offset=0Fix Generator content blocks. Excludes Authority Capture blocks and dismissed items.

Response

200 OK
{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "block_type": "faq_block",
      "title": "FAQ: What is the best AEO tool for B2B SaaS?",
      "target_prompt": "What is the best AEO tool for B2B SaaS?",
      "status": "generated",
      "created_at": "2026-06-13T09:00:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "limit": 50,
    "offset": 0,
    "business_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
POST/api/v1/scansTrigger a new AEO scan. Consumes scan_prompts_used the same as a dashboard-triggered scan.

Request body

application/json
{
  "prompts": ["What is the best AEO tool for B2B SaaS?"],
  "engines": ["chatgpt", "perplexity", "gemini"],
  "language": "en",
  "region": "us",
  "scanName": "Weekly API scan"
}

Response

202 OK
{
  "data": {
    "jobId": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "scanGroupId": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "totalTasks": 3,
    "promptCost": 1,
    "promptsRemaining": 9999
  }
}
GET/api/v1/scans/status/{jobId}Poll the status of a triggered scan job. Returns per-engine results as tasks complete.

Response

200 OK
{
  "data": {
    "jobId": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "status": "complete",
    "scanGroupId": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "totalTasks": 3,
    "tasksCompleted": 3,
    "tasksSucceeded": 2,
    "tasksFailed": 1,
    "overallScore": 38,
    "engineResults": {
      "chatgpt": "mentioned",
      "perplexity": "not_mentioned",
      "gemini": "mentioned"
    },
    "results": [
      {
        "engine": "ChatGPT",
        "engineId": "chatgpt",
        "prompt": "What is the best AEO tool for B2B SaaS?",
        "brandMentioned": true,
        "brandPosition": 2,
        "sentiment": "positive",
        "competitorsMentioned": ["Peec AI"],
        "mentionShareScore": 45
      }
    ],
    "error": null
  }
}
GET/api/v1/authority?limit=50&offset=0List Authority Captures for your business. Requires Pro or Enterprise plan.

Response

200 OK
{
  "data": [
    {
      "id": "f6a7b8c9-d0e1-2345-f6a7-b8c9d0e12345",
      "source_type": "url",
      "source_url": "https://g2.com/products/truecite/reviews",
      "original_filename": null,
      "transcript_words": 1240,
      "status": "done",
      "error_message": null,
      "blocks_generated": 3,
      "blocks_error": null,
      "created_at": "2026-06-14T09:00:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "pendingJobs": []
  }
}
POST/api/v1/authorityTrigger a new Authority Capture from a URL or pasted transcript. PDF upload is not supported via API — extract text client-side and pass it as transcript. Returns a jobId to poll.

Request body

application/json
{
  "sourceType": "url",
  "sourceUrl": "https://g2.com/products/truecite/reviews"
}

Response

202 OK
{
  "data": {
    "jobId": "g7h8i9j0-k1l2-3456-m7n8-o9p0q1r2s3t4"
  }
}
GET/api/v1/authority/status/{jobId}Poll the status of an authority capture job. Note: job status (queued/processing/complete/failed) and capture status (done/failed) use different value sets.

Response

200 OK
{
  "data": {
    "jobId": "g7h8i9j0-k1l2-3456-m7n8-o9p0q1r2s3t4",
    "status": "complete",
    "error": null,
    "capture": {
      "id": "f6a7b8c9-d0e1-2345-f6a7-b8c9d0e12345",
      "source_type": "url",
      "source_url": "https://g2.com/products/truecite/reviews",
      "original_filename": null,
      "transcript_words": 1240,
      "status": "done",
      "error_message": null,
      "blocks_generated": 3,
      "blocks_error": null,
      "created_at": "2026-06-14T09:00:00Z"
    }
  }
}
GET/api/v1/authority/{id}/blocksRetrieve the generated AEO content blocks for a capture. Returns full content (html_content, plain_text, json_ld).

Response

200 OK
{
  "data": [
    {
      "id": "h8i9j0k1-l2m3-4567-n8o9-p0q1r2s3t4u5",
      "block_type": "faq_block",
      "title": "FAQ: What do G2 reviewers say about TrueCite?",
      "html_content": "<div class=\"faq-item\"><h3>...</h3><p>...</p></div>",
      "plain_text": null,
      "json_ld": null,
      "status": "generated",
      "created_at": "2026-06-14T09:01:00Z"
    },
    {
      "id": "i9j0k1l2-m3n4-5678-o9p0-q1r2s3t4u5v6",
      "block_type": "answer_block",
      "title": "Answer paragraph for AI engines",
      "html_content": null,
      "plain_text": "TrueCite users on G2 highlight...",
      "json_ld": null,
      "status": "generated",
      "created_at": "2026-06-14T09:01:00Z"
    },
    {
      "id": "j0k1l2m3-n4o5-6789-p0q1-r2s3t4u5v6w7",
      "block_type": "schema_jsonld",
      "title": "FAQ Schema markup",
      "html_content": null,
      "plain_text": null,
      "json_ld": "{\"@context\":\"https://schema.org\",\"@type\":\"FAQPage\",\"mainEntity\":[...]}",
      "status": "generated",
      "created_at": "2026-06-14T09:01:00Z"
    }
  ]
}
POST/api/v1/authority/{id}/regenerateRe-run Claude Haiku block generation for an existing capture. Synchronous — returns updated blocks in the response. Counts against your monthly Authority Capture limit (20/mo on Pro, unlimited on Enterprise).

Response

200 OK
{
  "data": {
    "blocksGenerated": 3,
    "error": null,
    "blocks": [
      {
        "id": "k1l2m3n4-o5p6-7890-q1r2-s3t4u5v6w7x8",
        "block_type": "faq_block",
        "title": "FAQ: What do G2 reviewers say about TrueCite?",
        "html_content": "<div class=\"faq-item\">...</div>",
        "plain_text": null,
        "json_ld": null,
        "status": "generated",
        "created_at": "2026-06-14T09:05:00Z"
      }
    ]
  }
}
GET/api/v1/crawler-check?limit=50&offset=0Crawler check history: paginated AI bot access audits for your business, ordered by most recent.

Response

200 OK
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "domain": "https://acmecorp.com",
      "score": 75,
      "bots_allowed": 7,
      "bots_total": 8,
      "llms_txt_found": true,
      "sitemap_found": true,
      "result_json": { "domain": "https://acmecorp.com", "botStatuses": [...], "overallHealthy": false },
      "scanned_at": "2026-06-14T10:00:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "limit": 50,
    "offset": 0,
    "business_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
POST/api/v1/crawler-checkRun an AI bot access audit for a domain. Checks robots.txt, homepage blocking signals, WAF detection, llms.txt, and sitemap. Returns a jobId to poll.

Request body

application/json
{
  "url": "https://acmecorp.com"
}

Response

202 OK
{
  "data": {
    "jobId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}
GET/api/v1/crawler-check/status/{jobId}Poll a crawler check job. When complete, result contains the full bot access audit with per-bot allow/block status.

Response

200 OK
{
  "data": {
    "jobId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "complete",
    "error": null,
    "result": {
      "domain": "https://acmecorp.com",
      "robotsFetched": true,
      "botStatuses": [
        { "key": "GPTBot", "label": "GPTBot", "company": "OpenAI / ChatGPT", "allowed": true, "explicitly": "allowed" },
        { "key": "ClaudeBot", "label": "ClaudeBot", "company": "Anthropic / Claude", "allowed": false, "explicitly": "blocked" }
      ],
      "blockedCount": 1,
      "blockedHighImpact": ["ClaudeBot"],
      "crawlSim": { "status": 200, "accessible": true, "blockingSignals": [], "wafDetected": null },
      "llms": { "found": true, "contentBytes": 1420 },
      "sitemap": { "found": true, "excerpt": "42 URLs indexed" },
      "overallHealthy": false
    }
  }
}
GET/api/v1/llms-check?limit=50&offset=0LLMs.txt check history: paginated scan records ordered by most recent. Includes score, has_llms_txt, and fix suggestions.

Response

200 OK
{
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "domain_scanned": "https://acmecorp.com",
      "score": 62,
      "has_llms_txt": true,
      "has_llms_full": false,
      "ai_bots_allowed": true,
      "has_link_tag": false,
      "fixes_needed": [
        { "id": "add-llms-full", "title": "Create /llms-full.txt", "severity": "low" }
      ],
      "scanned_at": "2026-06-14T10:00:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "business_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
POST/api/v1/llms-checkRun an llms.txt audit for a domain. Checks /llms.txt, /llms-full.txt, robots.txt bot permissions, and homepage link tags. Returns a jobId to poll.

Request body

application/json
{
  "url": "https://acmecorp.com"
}

Response

202 OK
{
  "data": {
    "jobId": "d4e5f6a7-b8c9-0123-defa-234567890123"
  }
}
GET/api/v1/llms-check/status/{jobId}Poll an llms.txt check job. When complete, result contains the full audit with score, signals, and actionable fix suggestions.

Response

200 OK
{
  "data": {
    "jobId": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "status": "complete",
    "error": null,
    "result": {
      "domain": "https://acmecorp.com",
      "score": 62,
      "hasLlmsTxt": true,
      "hasLlmsFullTxt": false,
      "botStatus": { "GPTBot": true, "ClaudeBot": true, "PerplexityBot": true, "anthropic-ai": true },
      "hasLinkTag": false,
      "signals": { "hasLlmsFullTxt": false, "hasWordCount1000": true, "hasPricingSection": true, "hasFaqSection": false },
      "fixes": [
        { "id": "add-llms-full", "title": "Create /llms-full.txt", "severity": "low", "description": "llms-full.txt is the extended version with complete documentation.", "code": "..." }
      ]
    }
  }
}
GET/api/v1/schema-audit?limit=50&offset=0Schema audit history: paginated scan records ordered by most recent. Includes score, schemas found/missing, and fix suggestions.

Response

200 OK
{
  "data": [
    {
      "id": "e5f6a7b8-c9d0-1234-efa0-b1c2d3e4f567",
      "domain_scanned": "https://acmecorp.com",
      "url_scanned": "https://acmecorp.com",
      "score": 62,
      "schemas_found": ["Organization", "WebSite"],
      "schemas_missing": ["FAQPage", "Article", "HowTo"],
      "fixes_needed": [
        { "id": "add-faq-schema", "title": "Add FAQPage JSON-LD schema", "severity": "high" }
      ],
      "status": "complete",
      "scanned_at": "2026-06-14T11:00:00Z"
    }
  ],
  "meta": {
    "total": 8,
    "limit": 50,
    "offset": 0,
    "business_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
POST/api/v1/schema-auditTrigger a Schema.org structured data audit for a URL. Scores JSON-LD schemas, Open Graph tags, meta tags, and headings. Returns a jobId to poll.

Request body

application/json
{
  "url": "https://acmecorp.com"
}

Response

202 OK
{
  "data": {
    "jobId": "e5f6a7b8-c9d0-1234-efa0-b1c2d3e4f567"
  }
}
GET/api/v1/schema-audit/status/{jobId}Poll a schema audit job. When complete, result contains the full analysis: score, schemas found/missing, OG tags, fix recommendations, and page data.

Response

200 OK
{
  "data": {
    "jobId": "e5f6a7b8-c9d0-1234-efa0-b1c2d3e4f567",
    "status": "complete",
    "result": {
      "domain": "https://acmecorp.com",
      "score": 62,
      "schemasFound": ["Organization", "WebSite"],
      "schemasMissing": ["FAQPage", "Article", "HowTo"],
      "allSchemaTypes": [
        { "type": "Organization", "found": true, "highValue": true },
        { "type": "FAQPage", "found": false, "highValue": true }
      ],
      "ogTags": { "title": "Acme Corp", "description": "AI-driven tools.", "image": "https://acmecorp.com/og.png", "type": "website" },
      "twitterCard": { "card": "summary_large_image", "title": "Acme Corp", "description": "" },
      "metaTags": { "title": "Acme Corp | AI Tools", "description": "AI-driven...", "canonical": "https://acmecorp.com/" },
      "headings": { "h1": 1, "h2": 4, "h3": 6 },
      "wordCount": 1420,
      "internalLinks": 12,
      "fixes": [
        { "id": "add-faq-schema", "severity": "high", "title": "Add FAQPage JSON-LD schema", "description": "...", "code": "<script type=\"application/ld+json\">...</script>" }
      ],
      "scoreBreakdown": { "hasOrg": true, "hasFaq": false, "hasArticleHow": false, "ogComplete": true, "metaComplete": true, "singleH1": true, "hasTwitter": true },
      "pageData": { "brandName": "Acme Corp", "description": "AI-driven tools.", "sameAs": [], "logo": "https://acmecorp.com/logo.png", "inLanguage": "en", "favicon": "https://acmecorp.com/favicon.ico", "canonical": "https://acmecorp.com/" }
    }
  }
}
GET/api/v1/schema-audit/{id}Retrieve a specific schema audit result by its row ID. Returns the full result including all scores, fix suggestions, and page metadata.

Response

200 OK
{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-efa0-b1c2d3e4f567",
    "status": "complete",
    "url_scanned": "https://acmecorp.com",
    "domain_scanned": "https://acmecorp.com",
    "scanned_at": "2026-06-14T11:00:00Z",
    "result": {
      "domain": "https://acmecorp.com",
      "score": 62,
      "schemasFound": ["Organization", "WebSite"],
      "schemasMissing": ["FAQPage", "Article", "HowTo"],
      "fixes": [ { "id": "add-faq-schema", "severity": "high", "title": "Add FAQPage JSON-LD schema", "description": "...", "code": "..." } ],
      "scoreBreakdown": { "hasOrg": true, "hasFaq": false, "hasArticleHow": false, "ogComplete": true, "metaComplete": true, "singleH1": true, "hasTwitter": true }
    }
  }
}
GET/api/v1/ai-seo-audit?limit=50&offset=0AI SEO audit results: all audited pages for the business, ordered by overall_score ASC (lowest first). Note: uses "data" key, not the legacy dashboard "results" key.

Response

200 OK
{
  "data": [
    {
      "id": "f6a7b8c9-d0e1-2345-fab0-c1d2e3f4a567",
      "url": "https://acmecorp.com/pricing",
      "technical_score": 72,
      "content_score": 58,
      "ai_seo_score": 45,
      "overall_score": 57,
      "issues": [
        { "type": "warning", "category": "ai_seo", "message": "No FAQPage schema found", "fix": "Add FAQPage JSON-LD with 3–5 Q&A pairs targeting your brand queries" },
        { "type": "info", "category": "content", "message": "Word count is 480 — aim for 600+", "fix": "Expand the page with additional supporting content" }
      ],
      "audited_at": "2026-06-14T12:00:00Z",
      "created_at": "2026-06-14T12:00:00Z"
    }
  ],
  "meta": {
    "total": 14,
    "limit": 50,
    "offset": 0
  }
}
POST/api/v1/ai-seo-auditTrigger a full AI SEO audit of the business website. Discovers URLs via sitemap, then crawls each page scoring technical, content, and AI-SEO signals. Returns a jobId to poll. 429 if an audit is already running.

Response

202 OK
{
  "data": {
    "jobId": "f6a7b8c9-d0e1-2345-fab0-c1d2e3f4a567",
    "totalPages": 14,
    "sitemapFound": true
  }
}
GET/api/v1/ai-seo-audit/status/{jobId}Poll an AI SEO audit job. Returns progress (pagesCompleted / totalPages) and the most recently audited URL. When complete, poll GET /ai-seo-audit for the full results list.

Response

200 OK
{
  "data": {
    "jobId": "f6a7b8c9-d0e1-2345-fab0-c1d2e3f4a567",
    "status": "running",
    "totalPages": 14,
    "pagesCompleted": 9,
    "percentComplete": 64,
    "currentUrl": "https://acmecorp.com/blog/aeo-guide",
    "error": null
  }
}
GET/api/v1/ai-seo-audit/{pageId}Retrieve a single page audit result by its row ID. Returns the full row including all scores and the complete issues array with fix suggestions.

Response

200 OK
{
  "data": {
    "id": "f6a7b8c9-d0e1-2345-fab0-c1d2e3f4a567",
    "business_id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://acmecorp.com/pricing",
    "technical_score": 72,
    "content_score": 58,
    "ai_seo_score": 45,
    "overall_score": 57,
    "issues": [
      { "type": "warning", "category": "ai_seo", "message": "No FAQPage schema found", "fix": "Add FAQPage JSON-LD with 3–5 Q&A pairs targeting your brand queries" },
      { "type": "critical", "category": "technical", "message": "Missing meta description", "fix": "Add a 120–155 character meta description summarising the page content" }
    ],
    "audited_at": "2026-06-14T12:00:00Z",
    "created_at": "2026-06-14T12:00:00Z"
  }
}

Code Examples

Pythonrequests library
import requests

API_KEY = "tc_live_..."
BASE_URL = "https://truecite.ai/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Get MentionShare score
ms = requests.get(f"{BASE_URL}/mentionshare", headers=headers).json()
print(f"MentionShare: {ms['data']['mention_share']}%")
print(f"By engine: {ms['data']['by_engine']}")

# Get recent scans (paginated)
scans = requests.get(f"{BASE_URL}/scans?limit=100&offset=0", headers=headers).json()
print(f"Total scans: {scans['meta']['total']}")
for scan in scans["data"]:
    status = "✓" if scan["brand_mentioned"] else "✗"
    print(f"  {status} {scan['ai_engine']} — {scan['prompt_used'][:50]}")
Node.jsfetch API
const API_KEY = 'tc_live_...'
const BASE_URL = 'https://truecite.ai/api/v1'
const headers = { 'Authorization': `Bearer ${API_KEY}` }

// Get MentionShare score
const ms = await fetch(`${BASE_URL}/mentionshare`, { headers }).then(r => r.json())
console.log('MentionShare:', ms.data.mention_share + '%')
console.log('By engine:', ms.data.by_engine)

// Get recent scans (paginated)
const scans = await fetch(`${BASE_URL}/scans?limit=100&offset=0`, { headers }).then(r => r.json())
console.log('Total scans:', scans.meta.total)
for (const scan of scans.data) {
  const status = scan.brand_mentioned ? '✓' : '✗'
  console.log(` ${status} ${scan.ai_engine} — ${scan.prompt_used.slice(0, 50)}`)
}

Webhooks

Subscribe to real-time events delivered to your own HTTPS endpoint. Webhooks are registered from Settings → Developer → Webhooks (Enterprise only). Each delivery is signed so you can verify it came from TrueCite.

Event types

scan.completed

Fires once when all tasks in a scan job finish processing.

Payload

{
  "event": "scan.completed",
  "data": {
    "jobId": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "scanGroupId": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "businessId": "550e8400-e29b-41d4-a716-446655440000",
    "businessName": "Acme Corp",
    "tasksSucceeded": 44,
    "tasksFailed": 1,
    "sentiment": {
      "positive": 12,
      "neutral": 8,
      "negative": 2,
      "not_mentioned": 22
    }
  },
  "timestamp": "2026-06-13T10:00:00.000Z"
}
mention.dropped

Fires when your 7-day MentionShare average drops more than 10 points vs the prior week.

Payload

{
  "event": "mention.dropped",
  "data": {
    "businessId": "550e8400-e29b-41d4-a716-446655440000",
    "businessName": "Acme Corp",
    "currentScore": 32,
    "previousScore": 51,
    "drop": 19
  },
  "timestamp": "2026-06-13T00:00:00.000Z"
}
competitor.detected

Fires when AI engines surface a new competitor name that is not already in your competitors list.

Payload

{
  "event": "competitor.detected",
  "data": {
    "businessId": "550e8400-e29b-41d4-a716-446655440000",
    "businessName": "Acme Corp",
    "newCompetitors": [
      { "name": "Peec AI", "count": 4, "engines": ["chatgpt", "gemini"] }
    ]
  },
  "timestamp": "2026-06-13T10:01:00.000Z"
}
authority.captured

Fires when an Authority Capture job completes and AEO content blocks have been generated.

Payload

{
  "event": "authority.captured",
  "data": {
    "businessId": "550e8400-e29b-41d4-a716-446655440000",
    "businessName": "Acme Corp",
    "captureId": "f6a7b8c9-d0e1-2345-f6a7-b8c9d0e12345",
    "sourceType": "url",
    "sourceUrl": "https://g2.com/products/truecite/reviews",
    "blocksGenerated": 3,
    "status": "done"
  },
  "timestamp": "2026-06-14T09:01:00.000Z"
}
crawler_check.completed

Fires when an AI bot access audit finishes. Payload includes a summary score and key signals (not the full result_json).

Payload

{
  "event": "crawler_check.completed",
  "data": {
    "businessId": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "https://acmecorp.com",
    "jobId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "complete",
    "score": 75,
    "botsAllowed": 7,
    "botsTotal": 8,
    "llmsTxtFound": true,
    "sitemapFound": true
  },
  "timestamp": "2026-06-14T10:00:30.000Z"
}
llms_check.completed

Fires when an llms.txt audit finishes. Payload includes score and presence signals.

Payload

{
  "event": "llms_check.completed",
  "data": {
    "businessId": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "https://acmecorp.com",
    "jobId": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "status": "complete",
    "score": 62,
    "hasLlmsTxt": true,
    "hasLlmsFullTxt": false
  },
  "timestamp": "2026-06-14T10:01:00.000Z"
}
schema_audit.completed

Fires when a Schema.org audit finishes. Payload includes score, schemas found/missing, and the URL audited.

Payload

{
  "event": "schema_audit.completed",
  "data": {
    "businessId": "550e8400-e29b-41d4-a716-446655440000",
    "businessName": "Acme Corp",
    "scanId": "e5f6a7b8-c9d0-1234-efa0-b1c2d3e4f567",
    "jobId": "e5f6a7b8-c9d0-1234-efa0-b1c2d3e4f567",
    "urlScanned": "https://acmecorp.com",
    "domainScanned": "https://acmecorp.com",
    "score": 62,
    "schemasFound": ["Organization", "WebSite"],
    "schemasMissing": ["FAQPage", "Article", "HowTo"],
    "status": "complete"
  },
  "timestamp": "2026-06-14T11:00:30.000Z"
}
ai_seo_audit.completed

Fires when a full-site AI SEO audit finishes. Payload includes page counts, average score, and a link back to the results list. Note: only fires from the primary completion path (page-worker), not the queue-processor catch-all path.

Payload

{
  "event": "ai_seo_audit.completed",
  "data": {
    "businessId": "550e8400-e29b-41d4-a716-446655440000",
    "businessName": "Acme Corp",
    "jobId": "f6a7b8c9-d0e1-2345-fab0-c1d2e3f4a567",
    "totalPages": 14,
    "pagesCompleted": 14,
    "avgScore": 63,
    "status": "complete"
  },
  "timestamp": "2026-06-14T12:05:00.000Z"
}

Signature verification

Every delivery includes an X-TrueCite-Signature-256 header containing sha256=<HMAC-SHA256 hex> computed over the raw JSON body using the plaintext signing secret shown once at endpoint creation. Verify before processing.

Node.js — webhook handlercrypto (built-in)
import { createHmac } from 'crypto'

const WEBHOOK_SECRET = process.env.TRUECITE_WEBHOOK_SECRET // tc_whsec_...

export async function POST(req) {
  const sig = req.headers.get('x-truecite-signature-256') // "sha256=abc123..."
  const body = await req.text()

  const expected = 'sha256=' + createHmac('sha256', WEBHOOK_SECRET)
    .update(body)
    .digest('hex')

  if (sig !== expected) {
    return new Response('Forbidden', { status: 403 })
  }

  const { event, data, timestamp } = JSON.parse(body)

  if (event === 'scan.completed') {
    console.log('Scan done, sentiment:', data.sentiment)
    console.log('Tasks:', data.tasksSucceeded, 'succeeded,', data.tasksFailed, 'failed')
  } else if (event === 'mention.dropped') {
    console.log('Drop alert:', data.drop, 'points')
  } else if (event === 'competitor.detected') {
    console.log('New competitors:', data.newCompetitors.map(c => c.name))
  } else if (event === 'authority.captured') {
    console.log('Capture done:', data.captureId, 'blocks:', data.blocksGenerated)
  } else if (event === 'crawler_check.completed') {
    console.log('Crawler check done — score:', data.score, '| bots allowed:', data.botsAllowed + '/' + data.botsTotal)
  } else if (event === 'llms_check.completed') {
    console.log('LLMs check done — score:', data.score, '| llms.txt found:', data.hasLlmsTxt)
  } else if (event === 'schema_audit.completed') {
    console.log('Schema audit done — score:', data.score, '| schemas found:', data.schemasFound)
  } else if (event === 'ai_seo_audit.completed') {
    console.log('AI SEO audit done —', data.pagesCompleted, 'pages | avg score:', data.avgScore)
  }

  return new Response('OK')
}

Your endpoint must respond with HTTP 200 within 10 seconds. On failure, TrueCite retries up to 3 times with exponential backoff via QStash. Register and manage webhook endpoints from Settings → Developer → Webhooks.

Error Codes

CodeMeaningSolution
401UnauthorizedAPI key is missing, invalid, or revoked. Check your Authorization header.
402Payment requiredPOST endpoints: subscription is unpaid, incomplete, or paused. Update your payment method. Also returned by POST /scans when scan_prompts are exhausted (code: insufficient_prompts).
403ForbiddenThis key belongs to a non-Enterprise account. API access requires an Enterprise plan.
429Rate LimitedExceeded 100 requests/hour. Check the Retry-After header for seconds until reset.
500Server ErrorSomething went wrong on our end. Retry after a few seconds.

Error response shape

{ "error": { "code": "unauthorized", "message": "Invalid or revoked API key" } }

Ready to integrate?

API access is available on Enterprise plans. Generate your key from Settings → Developer once on Enterprise.

Go to Developer Settings →Contact for Enterprise
truecite.

When buyers ask AI, your brand is the answer.

Product

  • Pricing
  • Features
  • Integrations
  • API Docs
  • Fix Generator
  • AI SEO Audit

Company

  • About
  • Careers
  • Security
  • Case Studies
  • Comparisons
  • Support
  • Status

Resources

  • Blog
  • Documentation
  • Tutorials
  • AEO Guide
  • AEO Explained
  • GEO Explained

Legal

  • Privacy Policy
  • Terms of Service
  • Cookie Policy
truecite.
© 2026 TrueCite · AI Collective Labs Inc
PrivacyTermsSupport