Developers

API & data

JSON over HTTPS, UTC ISO-8601 timestamps, immutable ids (co_…, sen_…, evt_…) and slugs for public URLs. Public GET endpoints need no key. Errors are `{ detail }` with 4xx/5xx.

Base URL: https://www.company-atlas.co/api/v1. Pagination: ?page=1&per_page=25 (max 200) → { items, page, per_page, total, pages }. Unknown parameters are ignored. Interactive OpenAPI docs: www.company-atlas.co/api/v1/docs.

Quick start

# latest structured events
curl -s "https://www.company-atlas.co/api/v1/live?limit=5" | jq '.items[] | {company: .company.display_name, type: .event_type, title, confidence_label, source_url}'

# a company with its metrics, coverage and signals
curl -s "https://www.company-atlas.co/api/v1/companies/stripe" | jq '{display_name, metrics, counts, coverage}'

# pricing events in Canada since September, most important first
curl -s "https://www.company-atlas.co/api/v1/events?event_type=PRICING&country=CA&since=2026-09-01T00:00:00Z&sort=importance"

# rankings: fastest hiring growth over 30 days in fintech
curl -s "https://www.company-atlas.co/api/v1/rankings?kind=hiring_growth&window=30d&industry=fintech"

# stream (SSE)
curl -N "https://www.company-atlas.co/api/v1/live/stream"

# export as NDJSON
curl -s "https://www.company-atlas.co/api/v1/export/events.ndjson?event_type=LEADERSHIP&limit=1000" > leadership.ndjson

Watchlists without an account

TOKEN=$(uuidgen | tr -d -)$(uuidgen | tr -d -)
curl -s -X POST "https://www.company-atlas.co/api/v1/watchlist" -H "X-CA-Owner-Token: $TOKEN" -H "content-type: application/json" -d '{"company":"stripe"}'
curl -s "https://www.company-atlas.co/api/v1/watchlist" -H "X-CA-Owner-Token: $TOKEN"
curl -s -X POST "https://www.company-atlas.co/api/v1/alerts" -H "X-CA-Owner-Token: $TOKEN" -H "content-type: application/json" \
  -d '{"name":"Stripe pricing","company":"stripe","condition":{"event_types":["PRICING"],"min_importance":0.5},"channel":"webhook","target":"https://example.com/hook"}'

Endpoints

Platform

Method	Path	Notes
GET	/stats	Global counters: companies, sensors, observations, changes, events, dataset age (cached 60 s)
GET	/stats/history?days=90	Daily global aggregates and the activity index
GET	/system	Public aggregate health
GET	/pulse	Homepage aggregate (live, movers, hiring, launches, pricing, AI, industries, countries, trending, index, map)
GET	/live?limit=50&since=&event_type=&min_importance=	Latest active events (no cache)
GET	/live/stream	Server-sent events: `event: event` with an Event JSON, `event: heartbeat` every 20 s; `?since=` supported

Endpoints

Companies

Method	Path	Notes
GET	/companies?q=&country=&industry=&tier=&public=&sort=&sparkline=1	Paginated CompanyCard rows (`page`, `per_page` ≤ 200)
GET	/companies/{slug}	Detail: aliases, domains, relationships, metrics with confidence, coverage, signals, sparklines
GET	/companies/{slug}/events	Events with filters `event_type, event_subtype, since, until, min_importance, surface`
GET	/companies/{slug}/timeline?filter=all\|products\|jobs\|pricing\|leadership\|locations\|legal\|news\|developer	Grouped by day
GET	/companies/{slug}/metrics?days=90	Current metrics + series
GET	/companies/{slug}/jobs?status=open\|removed\|all&ai=1	Listings + summary (`meta.summary`)
GET	/companies/{slug}/people · /products · /pricing · /locations · /news	Reconciled entities with first/last seen
GET	/companies/{slug}/sensors · /history · /similar	Sensors, historical page viewer index, similar companies
GET	/companies/compare?companies=stripe,adyen,block	Side-by-side metrics, series, events, jobs, locations (2–6)

Endpoints

Provenance

Method	Path	Notes
GET	/sensors/{id} · /snapshots · /changes	Sensor with company and latest snapshot; its versions and changes
GET	/snapshots/{id}	Normalised text, semantic blocks, extracted fields (≤ 200 kB)
GET	/snapshots/{id}/diff/{other_id}	Block-level diff computed on demand
GET	/changes/{id}	Change with diff, structured delta and derived events
GET	/events/{id}	Event with every corroborating source and detection time

Endpoints

Events, rankings, atlases

Method	Path	Notes
GET	/events?event_type=&country=&industry=&since=&min_importance=&min_confidence=&q=&origin=&sort=	Paginated events
GET	/events/types · /events/summary?days=7&group=type\|industry\|country	Taxonomy counts and deltas
GET	/rankings?kind=most_active\|hiring_growth\|…&window=24h\|7d\|30d\|90d\|1y&country=&industry=	Ranked CompanyCards with value and delta
GET	/industries · /industries/{slug} · /countries · /countries/{code}	Living indices per industry and country
GET	/signals?scope=company\|industry\|country\|global · /trends?window=7d · /map?metric=events_30d · /index	Signals, trending terms, map buckets, Global Corporate Activity Index

Endpoints

Search, watchlists, exports

Method	Path	Notes
GET	/search?q=&types=companies,events,… · /search/suggest?q= · /ask?q=	Grouped search, fast suggestions, natural-language routing
GET/POST/DELETE	/watchlist · /watchlist/{slug} · /alerts · /alerts/{id} · /alerts/deliveries	Owner-token endpoints (`X-CA-Owner-Token`, ≥ 24 chars, stored hashed)
GET	/export/events.{json,ndjson,csv}?since=&event_type=&country=&limit=10000	Streamed export
GET	/export/companies.{json,ndjson,csv}?country=&industry= · /export/jobs.ndjson?company=&since=	Streamed exports
GET	/sitemap?kind=companies\|industries\|countries&page= · /methodology	Indexable slugs; metric definitions

Conventions

Rate limits, caching, licensing

Anonymous: 120 requests / minute per IP; bursts above that return 429 with a Retry-After header. Higher limits, webhooks and bulk datasets on request by email to contact@spboucher.ai (free for research).
Public aggregates (/pulse, /stats, /rankings, /industries, /countries) are cached 60 s and served with Cache-Control: public, max-age=60; /live*, owner and admin routes are no-store.
Metrics are 0–100 floats rounded to one decimal, except hiring momentum (percentage, may be negative) and open jobs (integer). A metric without inputs is omitted or null — never zero.
Company lookups accept slug or id; slugs may change, ids never do. Unknown → 404 { "detail": "company not found" }.
Redistribution: derived data (events, metrics, entity facts, metadata) may be reused with attribution to Company Atlas and a link to the event page; raw page content is not redistributed.
Careful language is part of the contract: status: no_longer_listed, confidence_label and origin (deterministic · llm · hybrid · backfill) ship with every event — see methodology.

Shapes are documented in the repository (`docs/API.md`) and mirrored by the web client’s TypeScript types.