Quick Start

Three ways to connect to Lighthouse. Pick the path that fits your stack.

Need an API key? Go to Settings → API Keys in your Lighthouse dashboard. Keys use the format lh_xxx.

1. Claude Desktop / Claude Code (MCP)

Add Lighthouse as an MCP server in your claude_desktop_config.json:

JSON

{
  "mcpServers": {
    "lighthouse": {
      "url": "https://www.ahoylighthouse.com/api/mcp?key=lh_YOUR_KEY"
    }
  }
}

Restart Claude Desktop. You'll see Lighthouse tools in the tool picker immediately.

2. REST API

Call any endpoint with your API key in the Authorization header:

bash

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/visibility

3. Webhooks

Register a webhook to receive real-time notifications when your visibility changes:

bash

curl -X POST \
  -H "Authorization: Bearer lh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/lighthouse",
    "events": ["visibility_change", "citation_loss"]
  }' \
  https://www.ahoylighthouse.com/api/v1/webhooks

Authentication

Lighthouse supports two authentication methods: API keys for server-to-server integrations, and OAuth 2.0 for user-facing applications.

API Keys

The simplest way to authenticate. API keys use the format lh_xxx and can be passed via either header:

http

# Option 1: Authorization header (recommended)
Authorization: Bearer lh_YOUR_KEY

# Option 2: X-Api-Key header
X-Api-Key: lh_YOUR_KEY

# Option 3: Query parameter (MCP connections)
https://www.ahoylighthouse.com/api/mcp?key=lh_YOUR_KEY

OAuth 2.0

For apps that act on behalf of a Lighthouse user. Supports the Authorization Code flow with PKCE.

Endpoints

Endpoint	Description
`/oauth/authorize`	Authorization page — redirect users here
`/oauth/token`	Exchange code for tokens (POST)
`/oauth/revoke`	Revoke a token (POST)
`/oauth/register`	Dynamic client registration (POST)

Scopes

Scope	Description
`mcp:read`	Read visibility data, citations, competitors, scores
`mcp:write`	Trigger analyses, create content briefs, manage webhooks

Token Lifetimes

Token Type	Lifetime
Authorization code	10 minutes
Access token	1 hour
Refresh token	30 days

OAuth Flow Example

javascript

// 1. Redirect user to authorize
const authUrl = `https://www.ahoylighthouse.com/oauth/authorize?` +
  new URLSearchParams({
    response_type: 'code',
    client_id: 'YOUR_CLIENT_ID',
    redirect_uri: 'https://your-app.com/callback',
    scope: 'mcp:read mcp:write',
    code_challenge: codeChallenge,
    code_challenge_method: 'S256'
  });

// 2. Exchange code for tokens
const tokens = await fetch('https://www.ahoylighthouse.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authCode,
    redirect_uri: 'https://your-app.com/callback',
    client_id: 'YOUR_CLIENT_ID',
    code_verifier: codeVerifier
  })
}).then(r => r.json());

MCP Server

The Lighthouse MCP server exposes 41 tools, 5 resources, and 5 prompts to any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and custom agents.

Connection

Transport	Endpoint	Status
Streamable HTTP (modern)	`https://www.ahoylighthouse.com/api/mcp`	Recommended
SSE (legacy)	`https://www.ahoylighthouse.com/api/mcp/sse`	Supported

Claude Desktop Configuration

json

{
  "mcpServers": {
    "lighthouse": {
      "url": "https://www.ahoylighthouse.com/api/mcp?key=lh_YOUR_KEY"
    }
  }
}

Programmatic Connection

typescript

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'my-app', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
  new URL('https://www.ahoylighthouse.com/api/mcp?key=lh_YOUR_KEY')
);
await client.connect(transport);

// Call a tool
const result = await client.callTool({ name: 'get_brand_visibility' });

MCP Tools Reference

41 tools organized into eight functional groups. Each tool is callable via client.callTool({ name, arguments }) or automatically by Claude when connected via MCP.

Monitor Toolset

Real-time visibility tracking and citation intelligence.

get_brand_visibility — Cross-model AI visibility scores with trend

No parameters required. Returns visibility scores across all tracked LLMs with 7-day trend data.

Response

{
  "brand": "Acme Corp",
  "overallScore": 72,
  "trend": "+4.2%",
  "models": {
    "chatgpt": 78,
    "claude": 71,
    "perplexity": 68,
    "gemini": 65
  }
}

get_citation_analysis — Citation sources, gaps, and frequency analysis

No parameters required. Returns citation sources, frequency, and identified gaps.

Response

{
  "totalCitations": 142,
  "topSources": [
    { "url": "acme.com/docs/guide", "count": 23 }
  ],
  "gaps": ["pricing page", "API reference"]
}

get_citation_decay — Citation persistence: TTC, half-life, survival curves

No parameters required. Returns time-to-citation, half-life metrics, and survival analysis.

get_competitor_landscape — Competitor share of voice and trajectory

limit number Optional Maximum number of competitors to return

get_industry_benchmark — Brand rank vs industry peers

No parameters required.

get_commerce_visibility — Shopping platform presence (Google Shopping, Amazon, Walmart)

No parameters required.

Analyze Toolset

Deep analytical tools for understanding your AI positioning.

analyze_intent_coverage — 5-dimensional intent battery analysis

No parameters required. Analyzes functional, expertise, motivational, constraint, and decision_stage intents.

analyze_customer_journey — Awareness → consideration → decision performance

No parameters required. Returns journey health scores and stage-by-stage breakdown.

analyze_content_gaps — Topics where competitors appear but you don't

No parameters required. Returns gap topics with suggested content briefs.

analyze_competitive_positioning — Head-to-head trajectory scoring

competitor string Optional Specific competitor to analyze. Omit for full landscape.

analyze_ground_truth — Accuracy verification, hallucination detection

No parameters required. Verifies factual accuracy of LLM statements about your brand. Returns 50+ actionable recommendations.

get_expert_strategy — Full Aurora AI strategic briefing

question string Optional Focus the strategy on a specific question

Act Toolset

Generate content, trigger analyses, and query the knowledge base.

get_recommendations — Aurora-powered strategic recommendations

question string Optional Focus recommendations on a specific area

generate_content_brief — AI-citation-optimized content brief

topic string Required Topic to generate a content brief for

format string Optional Output format (e.g. "blog", "landing-page", "faq")

generate_report — Executive report generation

reportType string Optional One of: "readiness", "competitive", "summary"

run_analysis — Trigger brand analysis (async)

No parameters required. Triggers a fresh analysis run. Subscribe to the analysis_complete webhook for completion.

search_knowledge_base — Query Aurora's expert knowledge base

query string Required Search query

category string Optional Filter by knowledge category

topK number Optional Number of results to return (default: 5)

get_proactive_insight — Single high-impact observation

No parameters required. Returns one of: win, opportunity, warning, or trend.

Configure Toolset

Pipeline status, project management, and per-model breakdowns.

get_brand_schema_status — Intent/Fanout/Conversation pipeline status

No parameters required.

get_geo_scores — Page-level GEO readiness scores

minScore number Optional Filter pages with score above this threshold

maxResults number Optional Limit number of returned pages

list_projects — All projects with latest visibility scores

No parameters required.

get_model_comparison — Per-LLM performance breakdown

No parameters required. Returns visibility and citation data broken down by individual AI model.

Automate Toolset

Create, run, and manage AI automation agents and workflows.

manage_agents — Create, list, run, and manage AI automation agents

action enum required
Action: list, create, run, get, delete

agentId string
Agent ID (for run/get/delete actions)

templateSlug string
Template slug for create (e.g., content-gap-monitor, competitive-intel)

name string
Agent name for create

get_agent_templates — List available agent templates with step configurations

No parameters. Returns all templates including Content Gap Monitor, Competitive Intelligence, DADU Monitor, Citation Accuracy, and more with their step types and trigger options.

run_brand_schema — Trigger full Brand Schema pipeline

modules enum
Which modules: all (default), intent, fanout, conversation

run_conversation_journey — Multi-turn AI conversation journey testing

action enum required
Action: list-templates, create, list-runs, get-run

industry string
Industry for template (e.g., consumer_electronics, saas, healthcare)

journeyId string
Journey ID for run retrieval

runId string
Specific run ID for get-run

run_ground_truth_crawl — Accuracy verification across 11+ LLMs

riskLevel enum
Risk tolerance: low, medium (default), high

manage_content — Generate, score, and manage content for AI citation

action enum required
Action: generate, score, suggest-topics, calendar

topic string
Topic for generation

url string
URL to score for citation readiness

style string
Style: blog_post, landing_page, faq, guide

Intelligence Toolset

Access platform intelligence feeds — bot tracking, Reddit, Google Analytics, keywords, backlinks.

get_bot_tracking — Bot vs human traffic analysis

metric enum
Metric: summary (default), trend, top-pages, human-vs-bot, human-referrers

get_reddit_intelligence — Reddit brand intelligence and community sentiment

metric enum
Metric: overview (default), threads, questions, recommendations

get_google_analytics — GSC/GA4 data with AI visibility correlation

metric enum
Metric: gsc-data, ga4-data, correlation (default)

dateRange string
Date range: 7d, 30d (default), 90d

get_keyword_research — Keywords, cannibalization, trending searches

action enum required
Action: research, cannibalization, trending, page-analysis

seed string
Seed keyword or URL

get_backlink_analysis — Backlink profile, trends, and competitor gaps

metric enum
Metric: profile (default), trend, gaps

Platform Toolset

Manage integrations, view unified dashboards, and access cross-module intelligence.

manage_integrations — Check and manage Slack, Teams, WordPress, Google connections

action enum required
Action: status, list

service string
Service: slack, teams, wordpress, google, cms

get_unified_dashboard — Cross-module executive scorecard

format enum
Format: scorecard (default), trend, export

Data Correlation Toolset

Talkwalker-compatible data correlation tools — histograms, forecasting, regional visibility, citation sources, and full-text search.

get_visibility_histogram — Faceted time-series with configurable intervals and breakdowns

interval string
Time bucket: hour, day, week, month

metric string
Metric to plot: visibility, sentiment, geoScore, citations

breakdown string
Breakdown dimension: model, topic, competitor

startDate string
ISO 8601 start date

endDate string
ISO 8601 end date

get_citation_sources — Top domains cited by AI models, ranked by frequency

limit number
Maximum sources to return

sort string
Sort order: frequency (default) or recency

get_regional_visibility — AI visibility filtered by geographic region

region string
Region filter: us, uk, eu, apac, global

get_visibility_forecast — Forecast future AI visibility with confidence intervals

forecastDays number
Days to forecast (7–90)

metric string
Metric to forecast: visibility, sentiment, geoScore, citations

search_ai_responses — Full-text search across AI responses, prompts, and citations

query string required
Search query text

type string
Filter by type: prompt, response, citation

limit number
Maximum results to return

MCP Resources

Subscribable resources that expose brand data as structured context for AI models. Resources use URI templates with {brandId} (your project UUID).

URI Template	Name	Description
`lighthouse://brand/{brandId}/visibility`	Brand Visibility	Subscribable visibility scores with trend data across all tracked models
`lighthouse://brand/{brandId}/citations`	Citation Status	Citation count, top sources, and recent changes
`lighthouse://brand/{brandId}/competitors`	Competitor Rankings	Competitor rankings by mention frequency and share of voice
`lighthouse://brand/{brandId}/decay`	Citation Decay	Half-life, time-to-citation, and outcome categories
`lighthouse://brand/{brandId}/journey-health`	Journey Health	Journey health scores across awareness, consideration, and decision stages

Subscribing to Resources

typescript

// Subscribe to visibility changes
await client.subscribeResource({
  uri: 'lighthouse://brand/YOUR_BRAND_ID/visibility'
});

client.on('resourceUpdated', (notification) => {
  console.log('Visibility changed:', notification);
});

MCP Prompts

Pre-built prompt templates that orchestrate multiple tools into comprehensive analyses. Use these via client.getPrompt() or from the prompt picker in Claude Desktop.

Prompt	Arguments	What It Does
`weekly_report`	none	7-day visibility report with wins, losses, and top 3 recommended actions
`competitor_deep_dive`	`competitor`: string	Deep analysis of a specific competitor's AI strategy, positioning, and trajectory
`content_audit`	`url`: string	Score a page for citation readiness with specific fix recommendations
`campaign_brief`	`topic`: string	Content brief targeting citation gaps for a specific topic
`full_diagnostic`	none	Comprehensive 10-tool diagnostic with scorecard and prioritized action plan

Using a Prompt

typescript

const prompt = await client.getPrompt({
  name: 'competitor_deep_dive',
  arguments: { competitor: 'Acme Corp' }
});
// prompt.messages contains the structured prompt ready for an LLM

REST API Reference

28 endpoints. All endpoints require authentication via API key or OAuth token. Base URL: https://www.ahoylighthouse.com

Core Analytics

GET /api/v1/visibility — Current visibility scores

Returns aggregate visibility score and per-model breakdown.

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/visibility

Response 200

{
  "score": 72,
  "trend": 4.2,
  "models": {
    "chatgpt": { "score": 78, "trend": 2.1 },
    "claude": { "score": 71, "trend": 5.8 },
    "perplexity": { "score": 68, "trend": 3.4 },
    "gemini": { "score": 65, "trend": 1.9 }
  },
  "updatedAt": "2026-05-20T14:30:00Z"
}

GET /api/v1/visibility/trend — Historical visibility trend

Returns daily visibility scores over a time range.

days number Optional Number of days of history (default: 30, max: 90)

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/visibility/trend?days=30"

GET /api/v1/geo-scores — Page-level GEO readiness

minScore number Optional Minimum score threshold

maxResults number Optional Limit results (default: 50)

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/geo-scores?minScore=50"

GET /api/v1/citations — Citation analysis

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/citations

Response 200

{
  "totalCitations": 142,
  "sources": [
    { "url": "acme.com/docs", "count": 23, "models": ["chatgpt", "perplexity"] }
  ],
  "gaps": ["pricing", "case-studies"],
  "newThisWeek": 8,
  "lostThisWeek": 2
}

GET /api/v1/citation-decay — Citation persistence metrics

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/citation-decay

Response 200

{
  "halfLife": 14.2,
  "timeToCitation": 3.5,
  "survivalRate30d": 0.62,
  "outcomes": {
    "persistent": 45,
    "decaying": 28,
    "lost": 12
  }
}

GET /api/v1/content-gaps — Content gap analysis

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/content-gaps

Competitive Intelligence

GET /api/v1/competitors — Competitor landscape

limit number Optional Max competitors to return (default: 10)

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/competitors?limit=5"

Response 200

{
  "competitors": [
    {
      "name": "Competitor A",
      "shareOfVoice": 0.34,
      "trend": -2.1,
      "mentions": 89
    }
  ]
}

GET /api/v1/competitor-positioning — Head-to-head analysis

competitor string Optional Specific competitor name

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/competitor-positioning?competitor=Acme"

GET /api/v1/industry-benchmark — Industry peer ranking

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/industry-benchmark

GET /api/v1/model-comparison — Per-LLM performance

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/model-comparison

Response 200

{
  "models": [
    { "model": "chatgpt", "visibility": 78, "citations": 45, "sentiment": 0.82 },
    { "model": "claude", "visibility": 71, "citations": 38, "sentiment": 0.89 },
    { "model": "perplexity", "visibility": 68, "citations": 52, "sentiment": 0.75 },
    { "model": "gemini", "visibility": 65, "citations": 29, "sentiment": 0.77 }
  ]
}

Strategic Analysis

GET /api/v1/recommendations — Aurora-powered recommendations

question string Optional Focus on a specific area

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/recommendations?question=improve+citations"

GET /api/v1/expert-strategy — Full strategic briefing

question string Optional Strategic question to focus the briefing

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/expert-strategy

GET /api/v1/intent-coverage — 5-dimensional intent analysis

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/intent-coverage

Response 200

{
  "dimensions": {
    "functional": { "score": 85, "coverage": 0.78 },
    "expertise": { "score": 72, "coverage": 0.65 },
    "motivational": { "score": 68, "coverage": 0.59 },
    "constraint": { "score": 55, "coverage": 0.42 },
    "decision_stage": { "score": 74, "coverage": 0.71 }
  },
  "overallScore": 71
}

GET /api/v1/journey-health — Customer journey health

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/journey-health

GET /api/v1/ground-truth-analysis — Accuracy verification

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/ground-truth-analysis

GET /api/v1/commerce-visibility — Shopping platform presence

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/commerce-visibility

Content & Actions

POST /api/v1/content-brief — Generate content brief

topic string Required Topic for the content brief

format string Optional Output format (blog, landing-page, faq)

curl

curl -X POST \
  -H "Authorization: Bearer lh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "AI visibility optimization", "format": "blog"}' \
  https://www.ahoylighthouse.com/api/v1/content-brief

GET /api/v1/knowledge-search — Search knowledge base

query string Required Search query

category string Optional Filter by category

topK number Optional Number of results (default: 5)

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/knowledge-search?query=schema+markup&topK=10"

GET /api/v1/brand-schema-status — Pipeline status

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/brand-schema-status

GET /api/v1/projects — List all projects

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/projects

Response 200

{
  "projects": [
    {
      "id": "proj_abc123",
      "name": "Acme Corp",
      "visibility": 72,
      "lastAnalysis": "2026-05-20T14:30:00Z"
    }
  ]
}

Webhook Management

POST /api/v1/webhooks — Register webhook

url string Required HTTPS endpoint to receive events

events string[] Required Array of event types to subscribe to

curl

curl -X POST \
  -H "Authorization: Bearer lh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.com/webhook", "events": ["visibility_change"]}' \
  https://www.ahoylighthouse.com/api/v1/webhooks

Response 201

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhook",
  "events": ["visibility_change"],
  "secret": "whsec_...",
  "createdAt": "2026-05-20T14:30:00Z"
}

GET /api/v1/webhooks — List webhooks

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/webhooks

DELETE /api/v1/webhooks — Remove webhook

id string Required Webhook ID to delete

curl

curl -X DELETE \
  -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/webhooks?id=wh_abc123"

Batch Operations

POST /api/v1/batch/visibility — Batch visibility check

Query visibility for multiple projects in a single request.

projectIds string[] Required Array of project IDs

curl

curl -X POST \
  -H "Authorization: Bearer lh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectIds": ["proj_abc", "proj_def", "proj_ghi"]}' \
  https://www.ahoylighthouse.com/api/v1/batch/visibility

Response 200

{
  "results": [
    { "projectId": "proj_abc", "score": 72, "trend": 4.2 },
    { "projectId": "proj_def", "score": 58, "trend": -1.3 },
    { "projectId": "proj_ghi", "score": 84, "trend": 6.7 }
  ]
}

Data Correlation

GET /api/v1/visibility/histogram — Faceted visibility time-series

Returns time-bucketed visibility data with configurable intervals and breakdowns. Talkwalker histogram format compatible.

interval string Optional Time bucket: hour, day, week, month (default: day)

metric string Optional Metric: visibility, sentiment, geoScore, citations (default: visibility)

breakdown string Optional Breakdown dimension: model, topic, competitor

startDate string Optional ISO 8601 start date

endDate string Optional ISO 8601 end date

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/visibility/histogram?interval=week&metric=visibility&breakdown=model"

Response 200

{
  "interval": "week",
  "metric": "visibility",
  "buckets": [
    { "date": "2026-05-12", "value": 68, "breakdown": { "chatgpt": 74, "claude": 62 } },
    { "date": "2026-05-19", "value": 72, "breakdown": { "chatgpt": 78, "claude": 66 } }
  ]
}

GET /api/v1/citation-sources — Top domains cited by AI models

Returns top citation source domains ranked by frequency. GEO equivalent of Talkwalker's Top Influencers.

limit number Optional Max sources to return (default: 20)

sort string Optional Sort: frequency (default) or recency

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/citation-sources?limit=10&sort=frequency"

Response 200

{
  "sources": [
    { "domain": "acme.com", "citations": 47, "models": ["chatgpt", "perplexity"] },
    { "domain": "docs.acme.com", "citations": 31, "models": ["claude", "gemini"] }
  ],
  "total": 142
}

GET /api/v1/search — Full-text search across AI responses

Search stored AI responses, prompt queries, and citations by keyword.

q string Required Search query

type string Optional Filter: prompt, response, or citation

limit number Optional Max results (default: 20)

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  "https://www.ahoylighthouse.com/api/v1/search?q=pricing+page&type=response&limit=10"

GET /api/v1/status — API status and account info

Returns API health, authentication status, remaining credits, and last analysis timestamp.

curl

curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://www.ahoylighthouse.com/api/v1/status

Response 200

{
  "apiVersion": "2.0.0",
  "authenticated": true,
  "credits": 4850,
  "lastAnalysis": "2026-05-20T14:30:00Z",
  "projectCount": 3
}

Webhooks

Receive real-time notifications when important changes happen. Webhooks are sent as HTTP POST requests to your registered URL.

Event Types

Event	Description	Trigger
`visibility_change`	Visibility score changed significantly	Score moves more than 5 points
`citation_loss`	A citation source was lost	Previously cited URL no longer appears
`citation_new`	New citation source detected	New URL cited by an AI model
`competitor_change`	Competitor landscape shift	Competitor gains/loses significant share
`decay_alert`	Citation decay warning	Citation half-life drops below threshold
`analysis_complete`	Analysis run finished	Triggered analysis completes processing

Payload Format

All webhook payloads share a common envelope:

json

{
  "id": "evt_abc123",
  "type": "visibility_change",
  "timestamp": "2026-05-20T14:30:00Z",
  "projectId": "proj_abc",
  "data": {
    "previousScore": 68,
    "currentScore": 74,
    "delta": 6,
    "model": "chatgpt"
  }
}

Verification

Each webhook includes an X-Lighthouse-Signature header containing an HMAC-SHA256 signature of the payload using your webhook secret. Always verify signatures before processing events.

javascript

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry Policy

Failed webhook deliveries (non-2xx response or timeout after 10 seconds) are retried with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours. After 4 failed attempts, the webhook is disabled and you will receive an email notification.

Code Examples

JavaScript / Node.js

Fetch visibility scores and run a competitor analysis:

javascript

const API_KEY = 'lh_YOUR_KEY';
const BASE = 'https://www.ahoylighthouse.com/api/v1';

async function getVisibilityDashboard() {
  const headers = { 'Authorization': `Bearer ${API_KEY}` };

  // Fetch visibility + competitors in parallel
  const [visibility, competitors] = await Promise.all([
    fetch(`${BASE}/visibility`, { headers }).then(r => r.json()),
    fetch(`${BASE}/competitors?limit=5`, { headers }).then(r => r.json())
  ]);

  console.log(`Visibility: ${visibility.score} (trend: ${visibility.trend}%)`);
  console.log(`Top competitor: ${competitors.competitors[0].name}`);
}

getVisibilityDashboard();

Python

Batch visibility check for multiple projects:

python

import requests

API_KEY = "lh_YOUR_KEY"
BASE = "https://www.ahoylighthouse.com/api/v1"

# Batch visibility for multiple projects
response = requests.post(
    f"{BASE}/batch/visibility",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "projectIds": ["proj_abc", "proj_def", "proj_ghi"]
    }
)

for result in response.json()["results"]:
    print(f"{result['projectId']}: {result['score']} (trend: {result['trend']})")

Claude Desktop — Full Configuration

Complete claude_desktop_config.json with Lighthouse enabled:

json

{
  "mcpServers": {
    "lighthouse": {
      "url": "https://www.ahoylighthouse.com/api/mcp?key=lh_YOUR_KEY"
    }
  }
}

// Once connected, try these in Claude Desktop:
// "What's my current AI visibility?"
// "Run a full diagnostic of my brand"
// "Generate a content brief for 'cloud migration'"
// "Who are my top competitors in AI search?"
// "Give me a weekly report"

Rate Limits & Best Practices

Rate Limits

Plan	Requests/min	Requests/day	Batch Size
Free	10	100	5 projects
Pro	60	5,000	50 projects
Enterprise	300	50,000	500 projects

Rate limit headers are included in every response:

http

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1716220800

Best Practices

Cache responses. Visibility scores update every few hours, not every second. Cache for at least 5 minutes.
Use batch endpoints. If you manage multiple brands, use /api/v1/batch/visibility instead of individual calls.
Subscribe to webhooks instead of polling for changes. Webhooks fire only when data actually changes.
Handle rate limits gracefully. When you receive a 429 response, wait until the X-RateLimit-Reset timestamp before retrying.
Use Streamable HTTP for new MCP integrations. SSE transport is maintained for backward compatibility only.

Error Handling

All error responses follow a consistent format:

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 2026-05-20T14:31:00Z",
    "status": 429
  }
}

Status	Code	Meaning
400	`invalid_request`	Missing or invalid parameters
401	`unauthorized`	Invalid or missing API key
403	`forbidden`	Insufficient permissions or scope
404	`not_found`	Resource does not exist
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Server error — retry with backoff

Developer Access Required

Lighthouse Developer Portal

Quick Start

1. Claude Desktop / Claude Code (MCP)

2. REST API

3. Webhooks

Authentication

API Keys

OAuth 2.0

Endpoints

Scopes

Token Lifetimes

OAuth Flow Example

MCP Server

Connection

Claude Desktop Configuration

Programmatic Connection

MCP Tools Reference

Monitor Toolset

Analyze Toolset

Act Toolset

Configure Toolset

Automate Toolset

Intelligence Toolset

Platform Toolset

Data Correlation Toolset

MCP Resources

Subscribing to Resources

MCP Prompts

Using a Prompt

REST API Reference

Core Analytics

Competitive Intelligence

Strategic Analysis

Content & Actions

Webhook Management

Batch Operations

Data Correlation

Webhooks

Event Types

Payload Format

Verification

Retry Policy

Code Examples

JavaScript / Node.js

Python

Claude Desktop — Full Configuration

Rate Limits & Best Practices

Rate Limits

Best Practices

Error Handling