TypeScript SDK
The API minus the plumbing. Auth, typed responses and pagination are already handled, so the first useful call is three lines rather than an afternoon. 13 resources, zero dependencies.
Quick Start
npm install @competlab/sdk
import CompetLab from '@competlab/sdk';
const cl = new CompetLab({ apiKey: process.env.COMPETLAB_API_KEY });
// See how AI systems rank your brand vs competitors
const visibility = await cl.aiVisibility.dashboard('proj_abc');
// Get a competitive Strategic Briefing
const briefing = await cl.strategicBriefing.get('proj_abc');
// Check competitor pricing changes
const pricing = await cl.pricing.dashboard('proj_abc');Available Resources
12 resources. All fully typed.
| Resource | Methods | Description |
|---|---|---|
| cl.health | check() | API health check |
| cl.projects | list(), get(id) | List and retrieve projects |
| cl.competitors | list(projectId), get(projectId, id) | Monitored competitors |
| cl.techTrust | dashboard(id), history(id), runDetail(id, runId) | Tech stacks & trust signals |
| cl.content | dashboard(id), history(id), runDetail(id, runId), changelog(id) | Content analysis & changes |
| cl.positioning | dashboard(id), history(id), runDetail(id, runId) | Homepage messaging & value props |
| cl.pricing | dashboard(id), history(id), runDetail(id, runId) | Pricing intelligence |
| cl.aiVisibility | dashboard(id), history(id), checkDetail(id, checkId), trend(id) | AI visibility across ChatGPT, Claude, Gemini, Perplexity and Google AI Overviews |
| cl.strategicBriefing | get(id) | AI-generated competitive Strategic Briefings |
| cl.alerts | list(id) | Competitive change alerts |
| cl.schedules | list(id) | Monitoring schedules |
| cl.tools | sitemapVisualizer(body), aiCrawlerChecker(body), fetchUrl(body), techStack.{startScan,getScan}, trustSignals.{startScan,getScan}, agentAdoption.{startScan,getScan} | On-demand site audits — the free-tool scans |
Authentication
One key per organisation, and it reaches every project in that organisation. Generate it in the CompetLab app under Your Organization → Settings → API Keys.
import CompetLab from '@competlab/sdk';
// Server side only — the key reaches every project in your organisation.
const cl = new CompetLab({ apiKey: process.env.COMPETLAB_API_KEY });Pass the key to the constructor and the SDK sends the CL-API-Key header for you — keys begin cl_live_. Competitive-intelligence data is read-only in v1; the on-demand site-audit tools use POST to start a scan. Keep the key server side: it is not scoped to a single project, so it should never reach a browser.
Troubleshooting
Every error carries a machine-readable code. Branch on that, never on the message — 5xx messages are a fixed string and will not tell you what happened.
No CL-API-Key header reached the API. Usually the environment variable is unset in the environment you actually deployed to, rather than the key being wrong.
The key was read but rejected. Revoked and expired are separate codes from invalid, so you can tell a rotated key from a typo without guessing.
The key authenticated but lacks the permission the call needs. v1 issues read scope; read_write is reserved for future write endpoints.
The project does not exist, or belongs to a different organisation than the key. Worth checking the second case before the first.
The project is real and the dimension simply has not been monitored yet. Not an error in your code — it means the first run has not landed.
Not enforced in v1. Keep requests under roughly 60 a minute as a courtesy; when limits do arrive they will come with Retry-After headers.
A null in a response is not a zero. It means we did not measure that field — a site timed out, blocked our crawler, or had no pricing page to read. Where a reason exists it arrives beside the value in a matching …Available object. Treat “we could not measure it” and “we measured zero” as different answers, because they are.
Build CompetLab into your product — or offer it to your clients
Build on it
The REST API and typed SDK pipe CompetLab's intelligence — every dimension, the Strategic Briefing, and the free scans — straight into your own product, dashboard, or workflow. Agencies run multiple client workspaces today with organizations, projects, and role-based access. (Programmatic org/project provisioning via the API is available on request.)
Start buildingResell or white-label
Reselling CompetLab to your clients, or want it white-labeled? Reach out — we'll scope it with you directly.
Talk to usStart Building with CompetLab
Get your API key and start querying competitive intelligence in minutes.
No credit card required