Skip to Content
DevelopersREST APIQuickstart

REST API Quickstart

Before you begin

New to CompetLab? Create a free account  and set up your first project first — the calls below list and read your projects, so you need one to get anything back.

You need a CompetLab API key. Create one in the dashboard under Settings → API Keys — it starts with cl_live_ and is 40 characters. Copy it when it’s shown; you won’t be able to read it again. (More in Authentication.)

List your projects

Every project-scoped call needs a projectId, and GET /v1/projects is where you get one:

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

The response wraps the list in items:

{
  "items": [
    {
      "id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "organizationId": "64f0a1b2c3d4e5f6a7b8c9d0",
      "name": "Acme",
      "domain": "acme.com",
      "status": "active",
      "competitorCount": 4,
      "lastMonitoredAt": "2026-07-07T09:12:00.000Z",
      "createdAt": "2026-06-01T10:00:00.000Z"
    }
  ]
}

Copy an id — that’s the projectId for the next call.

Pull a dimension

With a projectId, you can read any of the five monitored dimensions. Here’s the latest pricing intelligence:

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

A single resource comes back wrapped in item:

{
  "item": {
    "lastUpdatedAt": "2026-07-07T09:12:00.000Z",
    "summary": { "…": "pricing gap analysis" },
    "competitors": [
      {
        "domain": "rival.com",
        "isOwn": false,
        "pricingUrl": "https://rival.com/pricing",
        "content": { "…": "extracted plans" }
      }
    ]
  }
}

Swap pricing for ai-visibility, positioning, content, or tech-trust to read the other dimensions — or call strategic-briefing for the synthesized read across all of them.

Handle the response

  • Success is 200 with { item } or { items }. Paginated lists add a pagination object (page, limit, total, totalPages, hasMore).
  • A missing CL-API-Key header is 401 with code: "api_key_missing"; a malformed or unrecognized key is 401 with code: "api_key_invalid".
  • Other errors carry the same { error } envelope with a snake_case code and the HTTP status.

Next steps

Last updated on
OverviewAuthentication