CompetLab API Reference

Welcome to the CompetLab API documentation. This API provides programmatic access to your competitive intelligence data — technology stacks, content strategy, messaging & positioning, pricing plans, AI brand visibility across ChatGPT, Claude, Gemini, Perplexity, and Google AI Overviews, and — for Perplexity and Google AI Overviews — the pages they read when they answer your buyers' questions.

Who is this for?

• Developers building integrations with internal tools, CRMs, or BI platforms
• Agencies building whitelabel competitive dashboards for their clients
• AI agents and MCP servers consuming structured competitive data
• Automation platforms (Zapier, n8n) monitoring competitor changes

Authentication

All endpoints require a CL-API-Key header. Generate your API key in the CompetLab app under Your Organization → Settings → API Keys.

CL-API-Key: cl_live_a1b2c3d4e5f6...

Keys are organization-scoped — one key accesses all projects in your organization. Two permission scopes exist: read (current API) and read_write (future).

To manage your keys (create, revoke, set expiration): Your Organization → Settings → API Keys.

Response Format

Every response follows one of three shapes:

Single resource:

{ "item": { "id": "...", "name": "..." } }

Collection (with optional pagination):

{ "items": [...], "pagination": { "page": 1, "limit": 20, "total": 47, "totalPages": 3, "hasMore": true } }

Error:

{ "error": { "code": "project_not_found", "message": "Project not found", "status": 404 } }

Pagination uses ?page=1&limit=20 (1-indexed, default 20, max 100).

Error Codes

All errors return a machine-readable code field for programmatic handling:

Note on 5xx responses: The message field for 5xx errors is a static string ("Internal server error"). Branch on code for programmatic handling — do not pattern-match on message for 5xx.

Monitoring Dimensions

CompetLab monitors six dimensions of competitive intelligence:

Each dimension has three endpoints: a dashboard (latest monitoring data), history (paginated past runs), and run detail (full data for a specific historical run).

Strategic Briefing

Beyond the raw per-dimension data, /strategic-briefing returns the latest synthesized competitive briefing — the as-of read of what changed, what it means, and what to do, with an executive hub, deep-dives, a competitor dossier, and a ranked action plan. It synthesizes a broader analytical set than the monitored dashboards it reads — all six above, plus eight it researches for the briefing alone: landscape, funding, hiring/GTM, product launches and more. It is lean by default (request only the sections you need — it defaults to the hub, which doubles as the navigation map) and always carries methodology coverage caveats. See the endpoint for the full sections list.

Quick Start

Step 1 — Get your API key from Your Organization → Settings → API Keys in the CompetLab app

Step 2 — List your projects:

curl -H "CL-API-Key: cl_live_your_key_here" https://api.competlab.com/v1/projects

Step 3 — Get the latest pricing intelligence:

curl -H "CL-API-Key: cl_live_your_key_here" https://api.competlab.com/v1/projects/{projectId}/pricing

Additional Resources

• OpenAPI JSON Spec — Machine-readable API definition for code generators and integrations
• API Key Management — Your Organization → Settings → API Keys in the CompetLab app

Rate Limits

Rate limiting is not enforced in v1. We recommend keeping requests under 60 per minute as a best practice. Rate limits will be introduced in a future version with proper 429 responses and Retry-After headers.

Authentication: send your CompetLab API key as the CL-API-Key header (keys start with cl_live_, issued at app.competlab.com → Organization Settings → API Keys). The competitive-intelligence data is read-only in v1; the on-demand site-audit tools use POST to start a scan.

Endpoints

Every endpoint the live contract declares (39 in total). Parameters and response shapes for each are in the interactive explorer below, and in the machine-readable spec.

Errors

Errors return a JSON body describing the failure (an error object with a message and HTTP status). Standard HTTP status codes apply: 400 (invalid parameters), 401 (missing/invalid API key), 404 (not found), 429 (rate limited).