CompetLab REST API

What it is

The CompetLab REST API is the programmatic surface for your competitive intelligence. It’s a read API — every resource endpoint is a GET — that returns the same data you see in the app, as JSON, so you can pull it into your own backend, a scheduled job, or a dashboard you build. The free scan tools are POST endpoints — the quick ones (sitemap, AI-crawler, fetch-url) return their result inline, and the three longer scans (tech-stack, trust-signals, agent-adoption) return a scan you poll.

Reach for the REST API when the caller is your code. If the caller is an AI agent, the MCP server wraps this same API as agent-callable tools — pick the surface that matches who’s calling.

Base URL and versioning

Every request goes to https://api.competlab.com, and every route is versioned in the path:

https://api.competlab.com/v1/projects

The version lives in the URL (/v1), so a future /v2 can ship without breaking /v1 callers.

Authentication

Every request needs a CL-API-Key header carrying a CompetLab API key (it starts with cl_live_ and is 40 characters). You create keys in the dashboard under Settings → API Keys. The full story — creating keys, the format, and auth errors — is in Authentication.

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

Resources

The API mirrors the product: your projects and competitors, the five monitored dimensions, your alerts and schedules, the Strategic Briefing, and the free scan tools.

The complete, per-endpoint reference is generated from the spec in the API Reference. The live OpenAPI document is public at https://api.competlab.com/v1/docs/openapi.json, with Swagger UI at https://api.competlab.com/v1/docs.

Response shape

Responses are consistently wrapped:

• A single resource returns { "item": { … } }.
• A collection returns { "items": [ … ] }; paginated collections add a pagination object with page, limit, total, totalPages, and hasMore.
• Errors return { "error": { "code": "…", "message": "…", "status": 400 } }, where code is a machine-readable snake_case string.

null means unmeasured

One rule runs through every dimension, and it is the single most important thing to get right when you build on this data:

So hasFreePlan: false means we read the pricing page and there is no free plan. hasFreePlan: null means we could not read the page at all. The two are different facts and the API will not blur them: it would rather tell you nothing than tell you something it never checked.

This matters because the failure is silent. if (!hasFreePlan) treats “we couldn’t read it” and “they have no free plan” identically, and produces a confident sentence about a competitor from a measurement that never happened. Branch on null explicitly, and say “not measured” when you find it:

if (plan.hasFreePlan === null) {
  // We didn't measure this — say so, or say nothing.
} else if (plan.hasFreePlan === false) {
  // We measured it. There is no free plan. That's a finding.
}

The same rule applies to rates and counts: a null rate had nothing to compute from, so plot it as a break in the line rather than a zero. Per-field notes throughout the API Reference tell you what each null specifically means.

An omitted key is a third state

Some newer fields extend that rule rather than repeat it. Where null says we tried and could not measure this, an omitted key says reporting any value here would assert something we never established.

Tech & Trust’s aiAccess works this way. When a competitor’s robots.txt could not be read, assistantAccess and modelTrainingAccess are absent from the response, not empty — because [] would claim we evaluated all six assistants and none can reach the site, which is a completely different finding from “we couldn’t read the file.”

Note that measured_no_policy_found is a measurement: the site publishes no robots.txt, which under the robots exclusion standard permits every crawler, so the verdicts render and are all open. Only could_not_measure withholds them.

Rate limits

The free-tool endpoints are rate-limited per API key; the core resource endpoints aren’t throttled today. Over-limit requests get a 429. See Rate limits for the numbers.

Next steps

• Quickstart → — your first request in a minute.
• Authentication → — keys, format, and errors.
• API Reference → — every endpoint, generated from the spec.