# Company Atlas API — contract (v1)

Base: /api/v1 · JSON (orjson) · UTC ISO-8601 timestamps (Z) · immutable ids (co_…, sen_…, evt_…) · slugs for public URLs. Public GET endpoints need no auth. Owner endpoints (watchlists, alerts) take X-CA-Owner-Token (client-generated random string ≥ 24 chars, stored hashed). Admin endpoints take X-CA-Admin-Token. Errors: { "detail": string } with 4xx/5xx. Pagination: ?page=1&per_page=25 (max 200) → { items, page, per_page, total, pages }. Lists accept sort where documented; unknown params are ignored.

Interpretive language is careful by design (spec §167–168): events say "no longer listed", never "fired"; anything inferred carries a confidence (0–1) and a confidence_label (VERIFIED | HIGH_CONFIDENCE | LIKELY | INFERRED | LOW_CONFIDENCE).

# Shapes

type CompanyCard = {
  id: string; slug: string; display_name: string; legal_name: string | null; canonical_domain: string; website: string;
  description: string | null; industries: string[]; industry_primary: string | null; country: string | null; hq_city: string | null;
  hq_region: string | null; public_company: boolean; ticker: string | null; exchange: string | null; founded_year: number | null;
  employees_band: string | null; logo_url: string | null; status: string; onboarding_status: string; importance: number; tier: 1|2|3|4;
  metrics: Partial<Record<Metric, number>>;              // activity_score, hiring_momentum_30d, product_velocity, ai_adoption, corporate_change_index, open_jobs …
  counts: { sensors: number; observations: number; changes: number; events: number; jobs_open: number };
  last_event_at: string | null; last_observed_at: string | null;
  sparkline?: number[];                                  // 30 daily activity values when `?sparkline=1` (or on detail)
};
type Metric = 'activity_score'|'hiring_momentum_7d'|'hiring_momentum_30d'|'hiring_momentum_90d'|'open_jobs'|'ai_adoption'|'product_velocity'|
  'geo_expansion'|'developer_momentum'|'communication_activity'|'pricing_activity'|'leadership_activity'|'corporate_change_index'|'anomaly_score'|'historical_coverage';

type Event = {
  id: string; company: { id: string; slug: string; display_name: string; canonical_domain: string; country: string|null; logo_url: string|null };
  event_type: string; event_subtype: string; importance: number; confidence: number; confidence_label: string;
  title: string; summary: string | null; old_value: string | null; new_value: string | null;
  payload: Record<string, unknown>; entities: Record<string, unknown>; tags: string[];
  detected_at: string; effective_at: string | null; published_at: string | null;
  source_url: string | null; surface: string | null; sensor_id: string | null; change_id: string | null; cluster_id: string | null;
  origin: 'deterministic'|'llm'|'hybrid'|'backfill'; model_name: string | null; prompt_version: string | null; status: 'active'|'retracted'|'duplicate'|'review';
  sources?: { source_url: string; surface: string | null; detected_at: string; kind: string; sensor_id: string | null }[];   // detail only
};

type Sensor = {
  id: string; company_id: string; surface: string; connector_id: string; url: string; canonical_url: string; domain: string;
  status: string; tier: 'A'|'B'|'C'|'D'|'E'; quality_score: number; discovery_confidence: number; discovery_method: string | null;
  current_interval_s: number; next_run_at: string; last_run_at: string | null; last_success_at: string | null; last_change_at: string | null;
  last_status: number | null; last_failure_class: string | null; consecutive_failures: number;
  observation_count: number; snapshot_count: number; change_count: number; meaningful_change_count: number; event_count: number; created_at: string;
};

type Snapshot = { id: string; sensor_id: string; version_no: number; fetched_at: string; title: string | null; language: string | null;
  text_length: number | null; block_count: number | null; extracted_summary: Record<string, number>; content_hash: string; previous_snapshot_id: string | null };

type Change = { id: string; sensor_id: string; surface: string; company_id: string; detected_at: string; significance: number; kind: string;
  blocks_added: number; blocks_removed: number; blocks_modified: number; text_delta_ratio: number; similarity: number | null;
  snapshot_before: string | null; snapshot_after: string; diff?: DiffPayload; structured_delta?: Record<string, unknown> };

type DiffPayload = { added: BlockDelta[]; removed: BlockDelta[]; modified: BlockDelta[]; moved: string[]; counts: Record<string, number>;
  text_delta_ratio: number; similarity: number; reasons: string[] };
type BlockDelta = { key: string; kind: string; path: string; before: string | null; after: string | null; weight: number; similarity: number | null };

type Job = { id: string; title: string; department: string | null; location_text: string | null; city: string | null; country: string | null;
  remote: boolean | null; employment_type: string | null; seniority: string | null; url: string | null; posted_at: string | null;
  first_seen_at: string; last_seen_at: string; removed_at: string | null; status: 'open'|'no_longer_listed'; is_ai: boolean };

type Person = { id: string; name: string; title: string | null; role_category: string | null; is_executive: boolean; first_seen_at: string; last_seen_at: string; removed_at: string | null; status: string; source_url: string | null };
type Product = { id: string; name: string; category: string | null; description: string | null; url: string | null; first_seen_at: string; last_seen_at: string; removed_at: string | null; status: string };
type Plan = { id: string; plan_name: string; price: number | null; price_text: string | null; currency: string | null; billing_period: string | null; unit: string | null; features: string[]; contact_sales: boolean; version_no: number; valid_from: string; valid_to: string | null; status: string; source_url: string | null };
type Location = { id: string; kind: string; name: string | null; city: string | null; region: string | null; country: string | null; lat: number | null; lon: number | null; first_seen_at: string; last_seen_at: string; removed_at: string | null; status: string; source_url: string | null };
type NewsItem = { id: string; title: string; url: string; summary: string | null; category: string | null; published_at: string | null; first_seen_at: string; language: string | null };
type MetricPoint = { day: string; value: number; confidence: number };
type Signal = { id: string; company_id: string | null; scope: string; scope_key: string | null; kind: string; strength: number; confidence: number; title: string; explanation: string | null; evidence: Record<string, unknown>; window_days: number; detected_at: string; status: string };

# Endpoints

# Platform

# Companies

# Sensors, snapshots, changes (provenance)

# Events

# Rankings, industries, countries, signals, trends

# Search

# Watchlists & alerts (owner token)

# Exports & docs

# Admin (X-CA-Admin-Token)

# Rate limits & auth

Token bucket per process (refills continuously at limit / 60 tokens per second). Every limited response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Tier; when the bucket is empty the API answers 429 { "detail": "rate limit exceeded" } with a Retry-After (seconds). /health, /ready, /api/v1/docs and /api/v1/openapi.json are never limited. Keys are stored as sha256 hashes (api_keys.key_hash); the raw key is printed once by the CLI. last_used_at / request_count are updated lazily (≈ every 30 s). Owner endpoints (/watchlist, /alerts*) need X-CA-Owner-Token (client-generated, 24–200 chars); the owner row is created on first use and the token is only ever stored hashed. Admin endpoints answer 401 { "detail": "admin token required" } without a valid X-CA-Admin-Token.

# Implementation notes (API v1.0 — additive details)

• Caching / ETags. Cached public aggregates (/pulse 60 s, /stats 60 s, /system 30 s, /rankings 120 s, /industries*, /countries*, /index, /map, /trends, /events/types, /events/summary, /stats/history 300 s, /sitemap 600 s, /methodology 3600 s) return Cache-Control: public, max-age=N, stale-while-revalidate=2N plus a weak ETag; a matching If-None-Match yields 304. Other public GETs carry public, max-age=30…600 (per resource volatility); /live*, owner and admin routes are no-store. POST /admin/cache/clear?prefix= clears one key prefix (e.g. pulse, industries:) or everything.
• Pagination totals. total is exact up to 10 000 (bounded count) so deep feeds stay cheap; pages derives from it.
• /live also accepts country and industry; the payload is { items, count, cursor, server_time } — pass cursor back as since.
• /live/stream accepts ?since=&event_type=&min_importance=&max_s= (max_s ≤ 3600 bounds the connection for proxies with idle timeouts; the stream ends with event: end carrying the last cursor). The first message is always an event: heartbeat with {at, cursor}; event: event messages carry id: <event id>. Response headers include X-Accel-Buffering: no.
• /companies gains sort=relevance (automatic when q is present); q uses FTS (companies.search) for ≥ 3 characters with a trigram fallback and a prefix match for shorter strings. sparkline=1 adds 30 daily activity_score points.
• /companies/{slug} additionally returns company_type, employees, wikidata_id, indexed, discovered_at, first_observed_at, last_change_at, recent_events: Event[10] and sparkline.
• /companies/{slug}/timeline accepts filter=corporate (FINANCING, M&A, PARTNERSHIP, STRATEGY) and before=<iso>; items carry day.
• /companies/{slug}/jobs accepts department, remote, sort=recent|title|posted; q is a trigram ILIKE on title.
• /companies/{slug}/history accepts versions=1…20; /companies/{slug}/sensors?include_retired=1; /companies/{slug}/news?category=; /companies/{slug}/locations?status=all; /companies/{slug}/pricing?history_limit=.
• /companies/compare accepts days= (7–365) for the activity series; unknown slugs → 404 company not found: <slug>; fewer than 2 → 422.
• /events accepts status=active|retracted|duplicate|review|all (default active). Retracted events expose retracted_reason. /events/{id} embeds the full CompanyCard under company (a superset of CompanyRef), sources (falls back to the event's own source_url when event_sources is empty), change and cluster.
• /events/types lists every taxonomy type/subtype (count 0 when unseen) so filter UIs can render on an empty database.
• /events/summary items also carry previous (count of the preceding window).
• /rankings items are CompanyCard & { rank, value, delta }; the payload also lists kinds. hiring_growth/hiring_decline read hiring_momentum_7d|30d|90d according to the window; pricing_changes counts PRICING events in the window; delta is the difference with the metric_series value at the start of the window (null when no history yet).
• /countries/{code} accepts an ISO-2 code or a name slug (/countries/canada); CountryRow includes slug and subregion. /industries/{slug} adds children, signals, companies_total; trending is [] until per-industry trend data exists (never faked).
• /signals accepts scope_key, company, min_strength; items include a company ref when scoped to a company.
• /search people/products use trigram similarity (migrations/pending/api.sql adds the two supporting GIN indexes). /search/suggest items add slug / code / event_type next to href.
• /ask returns engine (deterministic | llm) and events_total; the parser is services/llm/ask.py when present (deterministic parse + optional LLM refinement), else api/ask_fallback.py. Answers only phrase measured counts.
• /snapshots/{id} accepts include=text,blocks,extracted and returns text_truncated (text capped at 200 kB), sensor, object_keys. /snapshots/{a}/diff/{b} orders the pair by fetched_at, returns source: "change" (stored diff, with change_id) or "computed" (sdk.diff.compare); 501 when the diff engine is unavailable, 404 when block objects are missing.
• Exports. /export/events.{fmt} also accepts until, company, min_importance, limit (≤ 10 000); /export/companies.{fmt} accepts status, tier, limit (≤ 20 000); /export/jobs.{json|ndjson|csv} accepts status=open|removed|all, country, ai, limit (≤ 10 000). CSV flattens the company ref (company_slug, company_name, company_domain, country).
• /sitemap pages hold 5 000 entries; kind=companies returns total; industries/countries only list entries with ≥ 1 active company.
• Admin additions. GET /admin/sensors accepts surface, sort=recent|next_run|failures|quality|changes|created; sensor actions return { ok, action, sensor, queued? , interval_s? } (set_interval is clamped to CA_MIN_INTERVAL_S…CA_MAX_INTERVAL_S and recomputes the tier). POST /admin/companies → 201 { ok, company, queued } (409 when the registrable domain already exists; 422 for non-http(s) URLs, unknown country codes or industry slugs). GET /admin/failures returns by_class and classes; GET /admin/queue returns counts + items; POST /admin/queue/requeue-dead { kind? }; GET /admin/llm includes stats; POST /admin/reviews/{id} accepts label (correct | duplicate | noise | misclassified) feeding /admin/quality.calibration; retract/restore append an audit trail under payload._audit and never delete; GET /admin/storage reports the object store. /admin/overview also returns companies_by_onboarding, scheduler_heartbeat.

# Conventions for implementers

• Every list endpoint is bounded (per_page ≤ 200, limit ≤ 500), uses indexed predicates, and returns Cache-Control: public, max-age=60 for public aggregates (/pulse, /stats, /rankings, /industries, /countries) and no-store for /live*, owner and admin routes.
• Company lookups accept slug or id. Unknown → 404 {detail: "company not found"}.
• Text search: Postgres FTS (companies.search, events.search) + trigram fallback for short/partial queries; never LIKE on unindexed columns.
• Numbers: metrics are 0–100 floats rounded to 1 decimal except hiring_momentum_* (percentage, may be negative) and open_jobs (int).
• Never fabricate: when a metric has no inputs, omit it (or null) rather than returning 0 as if measured.