API Documentation

The TrueCite REST API lets you track AI visibility and generate fix content programmatically. Available on Growth and Enterprise plans.

✓ REST API

✓ JSON responses

✓ Webhook support

Authentication

All API requests require an API key passed in the Authorization header. Get your API key from your dashboard settings.

Authorization headercurl

curl https://api.truecite.ai/v1/businesses \
  -H "Authorization: Bearer tc_live_your_api_key_here" \
  -H "Content-Type: application/json"

⚠️ Keep your API key secret. Never expose it in client-side code or public repositories. Rotate it immediately if compromised from your dashboard.

Base URL

Production

https://api.truecite.ai

Rate Limits

Plan	Requests/min	Scans/month	Concurrent scans
Growth	60	1,000	5
Enterprise	300	Custom	20

Endpoints

GET/v1/businessesList all businesses in your account

Response

200 OK

{
  "businesses": [
    {
      "id": "biz_abc123",
      "name": "Acme Corp",
      "website": "https://acme.com",
      "industry": "B2B SaaS",
      "created_at": "2026-05-01T00:00:00Z"
    }
  ]
}

POST/v1/scansTrigger a new AI visibility scan

Request Body

{
  "business_id": "biz_abc123",
  "prompts": [
    "What is the best AEO tool for B2B SaaS?",
    "How do I get my brand cited by ChatGPT?"
  ],
  "engines": ["chatgpt", "perplexity", "gemini", "claude"]
}

Response

200 OK

{
  "scan_id": "scan_xyz789",
  "status": "processing",
  "estimated_seconds": 30,
  "results_url": "https://api.truecite.ai/v1/scans/scan_xyz789"
}

GET/v1/scans/:scan_idGet scan results by ID

Response

200 OK

{
  "scan_id": "scan_xyz789",
  "status": "completed",
  "mention_share_score": 34,
  "results": [
    {
      "engine": "chatgpt",
      "prompt": "What is the best AEO tool?",
      "brand_mentioned": true,
      "brand_position": 2,
      "mention_share_score": 45,
      "competitors_mentioned": ["Profound", "HubSpot AEO"],
      "scanned_at": "2026-05-03T10:00:00Z"
    }
  ]
}

POST/v1/fixes/generateGenerate AEO fix content for a scan

Request Body

{
  "scan_id": "scan_xyz789",
  "engine": "chatgpt",
  "types": ["faq_block", "answer_paragraph", "json_ld"]
}

Response

200 OK

{
  "fix_id": "fix_def456",
  "engine": "chatgpt",
  "blocks": [
    {
      "type": "faq_block",
      "title": "FAQ Block",
      "content": "<div itemscope itemtype='https://schema.org/FAQPage'>..."
    },
    {
      "type": "answer_paragraph",
      "title": "Answer Paragraph",
      "content": "Acme Corp is the leading AEO platform for B2B SaaS..."
    },
    {
      "type": "json_ld",
      "title": "JSON-LD Schema",
      "content": "{"@context": "https://schema.org", ...}"
    }
  ]
}

GET/v1/mention-shareGet MentionShare trend data for a business

Response

200 OK

{
  "business_id": "biz_abc123",
  "current_score": 34,
  "trend": [
    { "date": "2026-04-27", "score": 20 },
    { "date": "2026-04-28", "score": 25 },
    { "date": "2026-04-29", "score": 28 },
    { "date": "2026-04-30", "score": 30 },
    { "date": "2026-05-01", "score": 34 }
  ]
}

GET/v1/competitorsList competitors for a business

Response

200 OK

{
  "competitors": [
    {
      "id": "comp_111",
      "name": "Profound",
      "website": "https://profound.co",
      "mention_count": 8
    }
  ]
}

Code Examples

Pythonrequests library

import requests

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

# Trigger a scan
scan = requests.post(f"{BASE_URL}/scans", headers=headers, json={
    "business_id": "biz_abc123",
    "prompts": ["What is the best AEO tool for B2B SaaS?"],
    "engines": ["chatgpt", "perplexity", "gemini"]
}).json()

print(f"Scan started: {scan['scan_id']}")

# Get results
import time
time.sleep(30)
results = requests.get(
    f"{BASE_URL}/scans/{scan['scan_id']}",
    headers=headers
).json()

print(f"MentionShare: {results['mention_share_score']}%")

Node.jsfetch API

const API_KEY = 'tc_live_your_api_key_here'
const BASE_URL = 'https://api.truecite.ai/v1'

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
}

// Trigger a scan
const scan = await fetch(`${BASE_URL}/scans`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    business_id: 'biz_abc123',
    prompts: ['What is the best AEO tool for B2B SaaS?'],
    engines: ['chatgpt', 'perplexity', 'gemini']
  })
}).then(r => r.json())

console.log('Scan started:', scan.scan_id)

// Get results after processing
await new Promise(resolve => setTimeout(resolve, 30000))
const results = await fetch(`${BASE_URL}/scans/${scan.scan_id}`, { headers })
  .then(r => r.json())

console.log('MentionShare:', results.mention_share_score + '%')

Webhooks

Receive real-time notifications when scans complete. Configure your webhook URL in dashboard settings.

Webhook payload — scan.completed

{
  "event": "scan.completed",
  "scan_id": "scan_xyz789",
  "business_id": "biz_abc123",
  "mention_share_score": 34,
  "scanned_at": "2026-05-03T10:00:00Z",
  "summary": {
    "total_prompts": 5,
    "mentioned": 2,
    "not_mentioned": 3,
    "engines": ["chatgpt", "perplexity", "gemini"]
  }
}

Error Codes

Code	Meaning	Solution
401	Unauthorized	Check your API key is valid and included in the Authorization header
403	Forbidden	This endpoint requires a higher plan (Growth or Enterprise)
404	Not Found	The resource ID does not exist or belongs to another account
429	Rate Limited	Slow down requests. Check the Retry-After header for when to retry
500	Server Error	Something went wrong on our end. Retry after a few seconds

Ready to integrate?

API access is available on Growth and Enterprise plans. Upgrade to get your API key.

Upgrade to Growth →Contact for Enterprise