Reference

API reference

All routes require Authorization: Bearer vs_…. Firehose is outbound — configure it in Settings → Webhooks. Replace BASE_URL and YOUR_API_KEY in the samples below.

Authentication

Send Authorization: Bearer vs_… on every call. Invalid or missing key → 401. Non-Pro team → 403. Production requires HTTPS.

Metered vs exempt

GET /health and GET /stats do not consume request budgets. Search, dossier, filters, and slices do — and attach X-RateLimit-* headers on 2xx. Details in Rate limits & security.

GET/api/v1/health

Uptime and dependency check. Exempt from request and record budgets — safe for monitoring probes.

Requires a valid Pro API key like every other route.
Returns 503 with status unavailable if the database check fails.

Example request

cURL

curl -s "${BASE_URL}/api/v1/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response 200 OK

JSON

{
  "status": "ok",
  "apiVersion": "v1",
  "timestamp": "2026-08-20T00:00:00.000Z"
}

Response fields

Field	Type	Description
status	string	"ok" or "unavailable"
apiVersion	string	Currently "v1"
timestamp	string	ISO time when status is ok

GET/api/v1/stats

Real-time usage snapshot: rate-limit buckets and static caps. Exempt from request budget.

Use remaining + resetUnix to pace clients instead of inventing counters.
See Rate limits & security for cap meanings.

Example request

cURL

curl -s "${BASE_URL}/api/v1/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response 200 OK

JSON

{
  "period": {
    "monthStart": "2026-08-01T00:00:00.000Z",
    "dayStart": "2026-08-20"
  },
  "rateLimits": {
    "perMinute": { "limit": 20, "used": 0, "remaining": 20, "resetUnix": 1724112060 },
    "dailyRequests": { "limit": 300, "used": 12, "remaining": 288, "resetUnix": 1724198400 },
    "monthlyRequests": { "limit": 3000, "used": 40, "remaining": 2960, "resetUnix": 1725148800 },
    "monthlyRecords": { "limit": 3000, "used": 100, "remaining": 2900, "resetUnix": 1725148800 },
    "monthlyPageTurns": { "limit": 200, "used": 2, "remaining": 198, "resetUnix": 1725148800 },
    "dailyCompanyDetail": { "limit": 100, "used": 1, "remaining": 99, "resetUnix": 1724198400 }
  },
  "staticLimits": {
    "pageSizeMax": 50,
    "querySetRecordsMax": 500
  }
}

Response fields

Field	Type	Description
period	object	Billing month start + UTC day key
rateLimits.*	object	limit, used, remaining, resetUnix per bucket
staticLimits	object	pageSizeMax, querySetRecordsMax

GET/api/v1/filters

Catalog of enums and match rules for company search and slice search. Does not run a search.

Discover allowed filter ids before building queries.
Consumes one request (not exempt).

Example request

cURL

curl -s "${BASE_URL}/api/v1/filters" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response 200 OK

JSON

{
  "filters": [
    {
      "id": "countries",
      "label": "Countries",
      "type": "enum",
      "appliesTo": ["companies", "slices"]
    }
  ]
}

Response fields

Field	Type	Description
filters	array	Filter definitions
filters[].id	string	Filter key / param id
filters[].appliesTo	string[]	Which endpoints accept it

POST/api/v1/companies

Company search. signal_query is required. Returns a thin list — enrich with GET /companies/{id}.

Missing signal_query → 422.
Each row in data counts toward monthly records.
page ≥ 2 consumes a page-turn quota.
Successful responses include X-RateLimit-* monthly headers.

Example request

cURL

curl -s -X POST "${BASE_URL}/api/v1/companies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signal_query": "signal:hiring:30d",
    "countries": ["US"],
    "page": 1,
    "pageSize": 50
  }'

Example response 200 OK

JSON

{
  "data": [
    {
      "id": "4066c846-48ea-403a-97b1-fd60503fdb97",
      "name": "Example Co",
      "domain": "example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 1,
    "totalPages": 1
  }
}

Response fields

Field	Type	Description
data	array	Thin company rows + overlays
data[].id	string	Company UUID
pagination	object	page, pageSize, total, totalPages

GET/api/v1/companies/{id}

Signal dossier for a company UUID (same ids as firehose company.id).

Unknown id → 404.
Counts toward daily company-detail and monthly records.
Prefer this after a firehose ping instead of re-searching.

Example request

cURL

curl -s "${BASE_URL}/api/v1/companies/4066c846-48ea-403a-97b1-fd60503fdb97" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response 200 OK

JSON

{
  "data": {
    "identity": {
      "id": "4066c846-48ea-403a-97b1-fd60503fdb97",
      "name": "Example Co",
      "domain": "example.com",
      "logo": null,
      "hqCountry": "US",
      "employeeCount": 120,
      "fundingStage": "series_a"
    },
    "signals": [],
    "aiAdoptionScore": {
      "score": 72,
      "intent": 18,
      "implementation": 20,
      "momentum": 16,
      "readiness": 18
    },
    "slices": []
  }
}

Response fields

Field	Type	Description
data.identity	object	Core company profile
data.signals	array	Public signal payloads for the company
data.aiAdoptionScore	object	Composite score + component breakdown
data.slices	array	Slice membership / notebook context

GET/api/v1/slices

Search inside one buying-window slice. Requires slice plus at least one filter.

Missing slice or filters → 422.
Unknown slice slug → 404.
Examples: ai-sdr-hiring, funded-ai-hiring, early-ai-adopters, …

Example request

cURL

curl -s "${BASE_URL}/api/v1/slices?slice=ai-sdr-hiring&countries=US&scoreMin=70" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response 200 OK

JSON

{
  "data": [
    {
      "companyId": "4066c846-48ea-403a-97b1-fd60503fdb97",
      "name": "Example Co",
      "score": 82
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 1,
    "totalPages": 1
  }
}

Response fields

Field	Type	Description
data	array	Companies in the slice window
data[].score	number	Slice adoption score
pagination	object	Standard page metadata