TypeScript SDK
The API minus the plumbing. Auth, typed responses and error codes are already handled, so the first useful call is three lines rather than an afternoon. 14 resources, zero dependencies.
Quick Start
npm install @competlab/sdk
import CompetLab from '@competlab/sdk';
const cl = new CompetLab({ apiKey: process.env.COMPETLAB_API_KEY });
// Who the AI models recommend in your category — and whether you are one of them
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
14 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.aiSources | dashboard(id), history(id), checkDetail(id, checkId) | The pages Perplexity and Google AI Overviews retrieved while answering, and who they name |
| cl.strategicBriefing | get(id), history(id), edition(id, runId) | AI-generated competitive Strategic Briefings |
| cl.tickets | list(id), get(id, ticketId), create(id, body), update(id, ticketId, body), move(id, ticketId, body), delete(id, ticketId), assignees(id), comments.{list,create,update,delete}, labels.{list,create,update,delete} | The Strategic Tickets board — read it, and with a read_write key write tickets, comments and labels |
| 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
A key belongs to one organization and reaches every project in it. 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 organization.
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. Strategic Tickets can also be written, with a key made with the read_write scope. A key reads everything its organization has and works its Strategic Tickets board on any plan and after one ends; the calls that fetch or scan a site on CompetLab's side need a plan. The on-demand site-audit tools use POST: three start a scan you then read with GET; the sitemap, AI-crawler and fetch-URL tools answer in the same call. 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 organization has no plan, and this call fetches or scans a site on CompetLab's side. Reads of what the organization already has, and every call on its Strategic Tickets board, succeed on the same key; the error's message says why, and what the person can do next.
The key authenticated but lacks the permission the call needs — usually a read key on an endpoint that writes. Strategic Tickets writes need a key made with the read_write scope.
The project does not exist, or belongs to a different organization 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.
The Strategic Tickets endpoints and the free tools allow 1,000 requests a minute per key, /tools/fetch-url 60; past that they answer 429 and the limit resets within a minute. The other endpoints are not rate limited today — keep them under about 60 a minute.
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. One exception: a rank. rankByPresence, and rank on the trend, is null on a company no answer named — that null is measured: not named in any answer.
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, the Strategic Tickets board (the part you can write to) 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
Your name on every edition comes with Agency, $999 a month (see /pricing). Reselling, or something custom? Reach out — we'll scope it with you.
Talk to usStart Building with CompetLab
Get your API key and start querying competitive intelligence in minutes.
No credit card required