Developer Access Required
This section is restricted to users with developer access. Contact your admin to request access, or return to the app.
Not logged in? Sign in first.
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.
https://api.ahoylighthouse.com/mcp
In Claude Code it's one command:
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:
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:
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:
# 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
| Endpoint | Description |
|---|---|
https://api.ahoylighthouse.com/oauth/authorize | Authorization page: redirect users here |
https://api.ahoylighthouse.com/oauth/token | Exchange code for tokens (POST) |
https://api.ahoylighthouse.com/oauth/revoke | Revoke a token (POST) |
https://api.ahoylighthouse.com/oauth/register | Dynamic client registration (POST) |
Scopes
| Scope | Description |
|---|---|
mcp:read | Read visibility, competitors, scores, citations, content gaps and reports. Always granted. |
mcp:write | Start analyses, agents and content generation. Spends credits. |
mcp:manage | Create workspaces and projects |
mcp:publish | Act outside Lighthouse: publish to your live site, activate ad spend, send email, pay research panels, create API keys, billing. Owners and admins only. |
mcp:admin | Platform-wide admin tools. Lighthouse staff only. |
Token Lifetimes
| Token Type | Lifetime |
|---|---|
| Authorization code | 10 minutes |
| Access token | 1 hour |
| Refresh token | 30 days |
OAuth Flow Example
// 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
| Transport | Endpoint | Status |
|---|---|---|
| Streamable HTTP | https://api.ahoylighthouse.com/mcp | Recommended |
| Streamable HTTP (alias) | https://api.ahoylighthouse.com/api/mcp | Supported |
| SSE (legacy) | https://api.ahoylighthouse.com/api/mcp/sse | Legacy |
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:
{
"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:
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
| Group | Tools |
|---|---|
| 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.
| Family | Covers | Tools |
|---|---|---|
| Agents | Agent definitions, runs, the builder, run Q&A and the template marketplace. | agent_runs, agent_config, agent_builder, agent_chat, agent_dashboard, agent_marketplace |
| Content | Content 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 |
| Creative | Asset 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 truth | Fact 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 |
| Insights | Aurora, 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 |
| Measurement | Dashboard 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 |
| Platform | Notifications, 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 |
| Research | AI 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 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
// 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.
| 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
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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/visibility
{
"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.
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
curl -H "Authorization: Bearer lh_YOUR_KEY" \ "https://api.ahoylighthouse.com/api/v1/geo-scores?minScore=50"
GET /api/v1/citations Citation analysis
curl -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/citations
{
"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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/citation-decay
{
"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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/content-gaps
Competitive Intelligence
GET /api/v1/competitors Competitor landscape
curl -H "Authorization: Bearer lh_YOUR_KEY" \ "https://api.ahoylighthouse.com/api/v1/competitors?limit=5"
{
"competitors": [
{
"name": "Competitor A",
"shareOfVoice": 0.34,
"trend": -2.1,
"mentions": 89
}
]
}
GET /api/v1/competitor-positioning Head-to-head analysis
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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/industry-benchmark
GET /api/v1/model-comparison Per-LLM performance
curl -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/model-comparison
{
"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
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
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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/intent-coverage
{
"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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/journey-health
GET /api/v1/ground-truth-analysis Accuracy verification
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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/commerce-visibility
Content & Actions
POST /api/v1/content-brief Generate content brief
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
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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/brand-schema-status
GET /api/v1/projects List all projects
curl -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/projects
{
"projects": [
{
"id": "proj_abc123",
"name": "Acme Corp",
"visibility": 72,
"lastAnalysis": "2026-05-20T14:30:00Z"
}
]
}
Webhook Management
POST /api/v1/webhooks Register webhook
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
{
"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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/webhooks
DELETE /api/v1/webhooks Remove webhook
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.
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
{
"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.
curl -H "Authorization: Bearer lh_YOUR_KEY" \ "https://api.ahoylighthouse.com/api/v1/visibility/histogram?interval=week&metric=visibility&breakdown=model"
{
"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.
curl -H "Authorization: Bearer lh_YOUR_KEY" \ "https://api.ahoylighthouse.com/api/v1/citation-sources?limit=10&sort=frequency"
{
"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.
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 -H "Authorization: Bearer lh_YOUR_KEY" \ https://api.ahoylighthouse.com/api/v1/status
{
"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:
{
"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.
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:
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:
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.
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 type | Requests/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:
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/visibilityinstead 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-Resettimestamp before retrying. - Use Streamable HTTP at
/mcpfor new MCP integrations. The SSE transport is kept for older clients only. - Send API keys in the
AuthorizationorX-Api-Keyheader, never as a?key=URL parameter, which leaks into logs and history.
Error Handling
All error responses follow a consistent format:
{
"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 |