Product
AI visibilityCompetitorsCitationsGEO score and page fixesPrompts and demandAI crawlers and referralsContent StudioAgents and automationsAurora strategistCommerceEarned mediaLocal networkAPI and MCPThe whole platform
Solutions
Brand and marketingSEO and GEO teamsContent teamsPR and communicationsE-commerceMulti-location and localAgenciesExecutives
Free tools
Free AI visibility scanPrompt set generatorAI readiness checkTemplates
Resources
Learn GEOUse casesHoliday AI Index 2026BlogNewsletterMethodologyDevelopersChangelogIntegrationsSecurity and trust
PricingAboutSign in
Check your AI visibilityBook a demo
Developer Portal

Lighthouse Developer Portal

Integrate AI visibility intelligence into your workflows via MCP or REST API

On this page

Getting Started

MCP Server

REST API

Reference

Quick Start

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

Need an API key for a script or automation? Create one in Settings → AI apps in your Lighthouse dashboard. Keys use the format lh_xxx. Apps you sign in to (Claude, ChatGPT, Cursor and the rest) don't need a key.

1. Claude, ChatGPT, Cursor and other AI apps (MCP)

Add Lighthouse as a remote MCP server with this URL. The app opens a Lighthouse sign-in, you choose what it may reach, and nobody copies a key.

text
https://api.ahoylighthouse.com/mcp

In Claude Code it's one command:

bash
claude mcp add --transport http lighthouse https://api.ahoylighthouse.com/mcp

Step-by-step setup for each app, with one-click installs for Cursor and VS Code, lives at ahoylighthouse.com/connect.

2. REST API

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

bash
curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://api.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://api.ahoylighthouse.com/api/v1/webhooks

Authentication

Lighthouse supports two ways in. AI apps that a person signs in to use OAuth 2.0. Scripts, automations and server-to-server integrations use API keys.

API Keys

Create a key in Settings → AI apps. A key belongs to one project and carries only the scopes you give it: read:analysis, mcp:read, mcp:write, mcp:manage and mcp:publish. Admin keys (admin:all) are for Lighthouse staff only. Keys use the format lh_xxx and go in a header:

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

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

Don't put a key in a URL (?key=). URLs end up in server logs, proxy logs and browser history. Send it in a header every time.

OAuth 2.0

For apps that act on behalf of a Lighthouse user. Supports the Authorization Code flow with PKCE and dynamic client registration, so MCP apps register themselves and nobody hands out a client ID. Discovery documents live at https://api.ahoylighthouse.com/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

On the consent screen the person signs in with an 8-digit code Lighthouse emails them, or with a password. They then pick what the app may reach (everything their role covers, including accounts created later, or only the workspaces and projects they select) and which scopes it gets. They can disconnect any app from Settings → AI apps.

Endpoints

EndpointDescription
https://api.ahoylighthouse.com/oauth/authorizeAuthorization page: redirect users here
https://api.ahoylighthouse.com/oauth/tokenExchange code for tokens (POST)
https://api.ahoylighthouse.com/oauth/revokeRevoke a token (POST)
https://api.ahoylighthouse.com/oauth/registerDynamic client registration (POST)

Scopes

ScopeDescription
mcp:readRead visibility, competitors, scores, citations, content gaps and reports. Always granted.
mcp:writeStart analyses, agents and content generation. Spends credits.
mcp:manageCreate workspaces and projects
mcp:publishAct outside Lighthouse: publish to your live site, activate ad spend, send email, pay research panels, create API keys, billing. Owners and admins only.
mcp:adminPlatform-wide admin tools. Lighthouse staff only.

Token Lifetimes

Token TypeLifetime
Authorization code10 minutes
Access token1 hour
Refresh token30 days

OAuth Flow Example

javascript
// 1. Redirect user to authorize
const authUrl = `https://api.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://api.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 125 tools, 5 resources and 5 prompts to any MCP client: Claude (web, Desktop and mobile), Claude Code, ChatGPT, Cursor, VS Code, Windsurf and your own agents. It identifies itself as Lighthouse (version 2.0.0) and sends instructions at initialize telling the model where to start.

Connection

TransportEndpointStatus
Streamable HTTPhttps://api.ahoylighthouse.com/mcpRecommended
Streamable HTTP (alias)https://api.ahoylighthouse.com/api/mcpSupported
SSE (legacy)https://api.ahoylighthouse.com/api/mcp/sseLegacy

Use /mcp for anything new. The SSE transport stays up for older clients only.

Adding Lighthouse to an app

Paste https://api.ahoylighthouse.com/mcp into the app's remote MCP server setting and sign in when it asks. Per-app steps live at ahoylighthouse.com/connect. For Cursor, the ~/.cursor/mcp.json entry looks like this:

json
{
  "mcpServers": {
    "lighthouse": {
      "url": "https://api.ahoylighthouse.com/mcp"
    }
  }
}

Programmatic Connection

Code that can't open a browser sends an API key in the Authorization header:

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://api.ahoylighthouse.com/mcp'),
  { requestInit: { headers: { Authorization: 'Bearer lh_YOUR_KEY' } } }
);
await client.connect(transport);

// Call a tool. Failed calls come back with isError: true.
const result = await client.callTool({ name: 'get_brand_visibility' });
if (result.isError) console.error(result.content[0].text);

MCP Tools Reference

The server registers 125 tools: 65 core tools and 60 more in ten families. Your app reads the live list (names, titles, input schemas) from tools/list, so treat that as the source of truth. This page tells you where to look.

Every tool carries a title and the standard MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so apps can ask before anything that changes data or spends credits. Many tools take an action argument; the allowed values are in the tool's input schema. When a call fails, the result comes back with isError: true and a message saying what went wrong.

Most tools need a project. On a sign-in connection, call list_accounts first and pass the project's id as projectId. An API key is already bound to one project.

Core tools

GroupTools
Start here
Find what this connection can reach, then get an overview.
list_accounts, list_projects, get_my_access, create_workspace, create_project, get_unified_dashboard
Visibility and citations
How AI answers mention and cite the brand.
get_brand_visibility, get_competitors, get_competitor_landscape, get_geo_scores, get_citation_analysis, get_citation_sources, get_citation_decay, get_content_gaps, get_model_comparison, get_industry_benchmark, get_commerce_visibility, get_visibility_histogram, get_regional_visibility, get_visibility_forecast, search_ai_responses
Analysis
Intent, journey, positioning and accuracy reads.
analyze_intent_coverage, analyze_customer_journey, analyze_competitive_positioning, analyze_ground_truth, get_brand_schema_status, get_measurement_comparison, get_topic_priorities, get_trend_annotations
Aurora strategy
Recommendations and the expert knowledge base.
get_recommendations, get_expert_strategy, get_proactive_insight, search_knowledge_base
Runs
These start work and spend credits. Poll the status tool they point to.
run_analysis, get_analysis_status, run_brand_schema, run_ground_truth_crawl, run_conversation_journey
Content, reports and agents
Briefs, drafts, reports and automation agents.
generate_content_brief, generate_report, manage_content, manage_agents, get_agent_templates
Traffic, search and integrations
Bot traffic, Search Console and GA4, keywords, backlinks.
get_bot_tracking, get_google_analytics, get_keyword_research, get_backlink_analysis, manage_integrations
Earned media
Journalists, publishers and media plans scored by AI citation.
get_journalist_index, get_journalist_profile, get_publisher_planner, score_media_plan, get_citation_graph
Restricted
Listed on every connection. The admin_ tools only run for Lighthouse staff and the wall_ tools only for accounts with wall access.
admin_list_projects, admin_get_full_analysis, admin_list_analyses, admin_get_prompt_results, admin_get_citations, admin_query_table, wall_status, wall_import_prompts, wall_start_run, wall_run, wall_promote, wall_snapshot

Tool families

Each family tool covers a whole product area behind one name and an action argument.

FamilyCoversTools
AgentsAgent definitions, runs, the builder, run Q&A and the template marketplace.agent_runs, agent_config, agent_builder, agent_chat, agent_dashboard, agent_marketplace
ContentContent Studio posts, the editorial calendar, the on-page action queue and the brand knowledge base.content_posts, content_calendar, content_studio, content_actions, content_knowledge_base
CreativeAsset Studio concepts and ad sets, ad network distribution, video GEO, Beacon pitch briefs and the Creators Index.creative_studio_read, creative_studio_generate, creative_studio_optimize, creative_studio_send_email, creative_ad_networks, creative_video_geo, creative_beacon, creative_creators
Ground truthFact accuracy: reads, comparison batches, recommendations, preflight checks, reports, alerts and the brand schema.gt_read, gt_compare, gt_recommendation, gt_preflight, gt_reports, gt_alerts, gt_brand_schema, gt_brand_schema_backfill
InsightsAurora, AI focus groups, pre-publication simulation, brand instruments, the Industry Monitor, site readiness linting and observations.insights_aurora, insights_focus_group, insights_simulate, insights_brand_instruments, insights_industry_monitor, insights_site_tools, insights_observations
MeasurementDashboard views, labels, saved views, schedules, forecasts, citation decay detail and the onboarding checklist.measurement_insights, measurement_labels, measurement_views, measurement_schedules, measurement_forecasts, measurement_dashboard, measurement_citation_decay, measurement_onboarding_checklist
PlatformNotifications, third-party connections, bot tracking detail, AI pages, agency workspaces, access, billing and prediction markets.platform_integrations, platform_connections, platform_bot_tracking, platform_shadow_sites, platform_agency, platform_access, platform_billing, platform_markets, platform_wall_admin
ResearchAI demand, conversation journeys, the Atlas map, query fanout, intent batteries, commerce and competitor pages.research_ai_demand, research_journeys, research_atlas, research_fanout, research_intent, research_commerce, research_competitors

What a tool may do depends on the scopes the connection holds. Reads need mcp:read. Runs and generation need mcp:write. Creating workspaces and projects needs mcp:manage. Anything that acts outside Lighthouse (publishing to your site, ad spend, sending email, billing) needs mcp:publish.

MCP Resources

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

URI TemplateNameDescription
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 chain several tools into one analysis. Use them via client.getPrompt() or from your app's prompt picker.

PromptArgumentsWhat 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://api.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://api.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://api.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://api.ahoylighthouse.com/api/v1/geo-scores?minScore=50"
GET /api/v1/citations Citation analysis
curl
curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://api.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://api.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://api.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://api.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://api.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://api.ahoylighthouse.com/api/v1/industry-benchmark
GET /api/v1/model-comparison Per-LLM performance
curl
curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://api.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://api.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://api.ahoylighthouse.com/api/v1/expert-strategy
GET /api/v1/intent-coverage 5-dimensional intent analysis
curl
curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://api.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://api.ahoylighthouse.com/api/v1/journey-health
GET /api/v1/ground-truth-analysis Accuracy verification
curl
curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://api.ahoylighthouse.com/api/v1/ground-truth-analysis
GET /api/v1/commerce-visibility Shopping platform presence
curl
curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://api.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://api.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://api.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://api.ahoylighthouse.com/api/v1/brand-schema-status
GET /api/v1/projects List all projects
curl
curl -H "Authorization: Bearer lh_YOUR_KEY" \
  https://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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

EventDescriptionTrigger
visibility_changeVisibility score changed significantlyScore moves more than 5 points
citation_lossA citation source was lostPreviously cited URL no longer appears
citation_newNew citation source detectedNew URL cited by an AI model
competitor_changeCompetitor landscape shiftCompetitor gains/loses significant share
decay_alertCitation decay warningCitation half-life drops below threshold
analysis_completeAnalysis run finishedTriggered 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://api.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://api.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: Custom Connector

In Claude, open Settings → Connectors, choose Add custom connector, name it Lighthouse and paste the server URL. Click Connect and sign in. The connector then works on the web, in Claude Desktop and on mobile.

text
https://api.ahoylighthouse.com/mcp

// Once connected, try these in Claude:
// "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

Limits apply per API key, in a fixed 60-second window. API access comes with paid plans: the read-only REST API from Professional, and the full API, the MCP server and webhooks from Business. See pricing.

Request typeRequests/min per key
Reads (REST endpoints and read tools)120
Writes (routes and tools behind mcp:write)20

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 at /mcp for new MCP integrations. The SSE transport is kept for older clients only.
  • Send API keys in the Authorization or X-Api-Key header, never as a ?key= URL parameter, which leaks into logs and history.

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
  }
}
StatusCodeMeaning
400invalid_requestMissing or invalid parameters
401unauthorizedInvalid or missing API key
403forbiddenInsufficient permissions or scope
404not_foundResource does not exist
429rate_limit_exceededToo many requests
500internal_errorServer error, retry with backoff

More resources