API docs

What the presented key resolves to. The response can only ever reflect the presented key's own customer, never another's.

5-min quickstart: curl/Python/TS/MCP/Clay snippets with the caller's own live key injected, plus an auto-created watch on a high-motion company on `body.webhook_url` so a webhook fires shortly after signup. Not billable -- getting started must never cost quota. Idempotent: re-opening the quickstart never mints a second watch or webhook endpoint.

Guided watch/webhook onboarding flow: first watch -> first signed webhook delivered -> the 80%-quota expansion nudge. Not billable, same as `/quickstart`. Idempotent: re-polling never mints a second watch or endpoint and never double-counts a delivery.

Account-scoped key listing -- every key (active and revoked) for the caller's own customer, with `last_used_at` from the usage ledger.

Self-serve key issuance: a developer who already holds one key can mint another for their OWN account -- no operator step. `scopes` is the only field the request body carries. The new key's customer AND its tier are both taken from the AUTHENTICATED caller's own key, never from the request, so a key can never be issued for another tenant nor carry more entitlement than the key that authorized it. Sending a `tier` is rejected with a 422 rather than ignored. To change your tier, change your plan -- the new tier then applies to every key on the account. The mint also inherits the parent key's acquisition surface, exactly as rotation carries it forward: an additional self-serve mint is the same acquisition, and the same entitlement, as the key that authorized it.

Self-serve key revocation, scoped to the caller's own customer -- revoking another tenant's key id 404s, identical to revoking one that doesn't exist at all (fail-fast, no cross-tenant leak).

Agent-driven key rotation: mints a replacement key bound to the SAME account and revokes `key_id` in one call -- an autonomous agent rotates its own credential without an operator or a human seat in the loop, so usage keeps billing to the account. Scoped to the caller's own customer; `key_id` need not be the presented key. 404 for an id that doesn't exist, belongs to another tenant, or is already revoked -- indistinguishable, same as `delete_key`.

Metered usage for the caller's customer over a rolling window -- `window` is hours (default 24). Aggregates across every key the customer holds, not just the one presented on this call. `keys[]` splits those same totals per key, so a customer holding one key per environment (or per client) can attribute its spend. It lists the keys with at least one metered event in the window, ascending by `key_id`; each of the five totals sums across `keys[]` to the customer-level number printed beside it.

Usage & billing dashboard: per-key usage vs quota (green/amber/red), the account's spend-cap status, an in-context 402 upgrade prompt when either is exhausted, and the 80%-quota expansion nudge -- every number read off the same meter enforced at request time. Not billable: reading the dashboard must never itself cost quota. `free_tier` reports the free allowance and how much of it this billing month has spent (null for an account holding no free key, which neither free wall can bind). `blocked_deliveries` counts the changes we DECIDED not to send you since that period began, per reason: `wall_blocked` is the free monthly change allowance, `cap_blocked` is your own spend cap. Both are terminal and are never retried, so a non-zero count is why a watch has gone quiet -- as distinct from nobody hiring.

Pause-instead-of-cancel: suspends metering for the caller's OWN account -- every billable route 403s with `account_paused` until resumed. Watches are untouched.

Resume a paused account -- the next billable call the caller's keys make is enforced normally again.

Cheap is-hiring gate -- ATS/board-only, freshness-floored: qualifies a company before an agent spends on a richer call. A free-tier account past its cost-to-serve cap degrades to a demand-signal-only path, returning `202 {status: "over_cap"}` instead of a served read -- the same convention as the cold-tail `202 {job_id, status: "crawling"}`.

The company's current active reqs, deduped across boards -- ATS/board-only, freshness-floored. The same real req posted on two boards appears once, with both boards listed. An unresolvable `function` -- anything that is not a function taxonomy id -- is rejected with 422 instead of returning a silently-empty result. `limit` is bounded: an oversized page is rejected with 422 rather than truncated.

Basic ATS/board-derived company firmographics -- no LinkedIn-derived field ever appears here by construction. Freshness-floored: `boards` only reflects ATS/board sources observed at or before the floor cutoff.

A company's hiring velocity/direction/momentum in one call -- the first paid route, honoring `max_age` (seconds). Cold (no ATS/board data at all, and `max_age` demands freshness beyond nothing) returns `202 {job_id, status: "crawling"}` instead of a synchronous body.

Reverse who's-hiring-for {role, geo}: companies with active reqs matching `role` (posting title) / `geo` (country) / `since` (first-seen lower bound), deduped by company, each with its full hiring pulse and the specific reqs that matched. ATS-only, freshness-floored, keyset-paginated via `next_cursor` (the last page's highest `company_id`). `role` is a full-text query over the raw posting title, not an id: type the role the way a posting would spell it (`staff engineer`), every word must match, and a role that matches nothing comes back as an empty page rather than an error. The two filters are deliberately asymmetric -- an unresolvable `geo` IS rejected with 422, because a country either is or is not in the stored vocabulary, whereas an unmatched title is an honest zero result. `industry`, `industry_terms` and `headcount_band` cut the corpus down to your ICP's companies. Repeat a parameter to OR its values; different parameters AND. They are filters only -- no company facet is added to the response by passing one -- and a company whose fact we do not hold is never matched, so a cut is honestly narrow rather than quietly padded. `limit` is bounded: this endpoint meters the billed `source_row` atom off its own serialized rows, so an unbounded page is an unbounded invoice. An out-of-range `limit` is rejected with 422 rather than silently truncated; page through the full set with `next_cursor`. The shared public demo key gets a tighter page instead -- it bills nothing, so no ledger-derived gate can bound it, and a full-size page would make a world-readable credential a bulk-export window onto the fresh index.

The live reqs matching a full ICP definition -- "senior Go roles at 51-200-person fintechs in the EU, agencies excluded" -- as a page you pull, rather than a webhook you register and wait on. `criteria` is the same closed vocabulary a watch takes (`POST /v1/watches`), evaluated here in SQL instead of on the dispatcher's tick: three namespaced groups (`company`, `req`, `event`), AND across groups and fields, OR within a field. A field outside the vocabulary is a 422, and so is one this projection cannot answer -- `event.function` (a Python-derived taxonomy bucket, not a column; use `req.job_family`) and `event.event_type` (a ledger transition, where a row here is a live posting; use `/v1/events`). Never a silently-ignored filter: a dropped criterion answers a wider question than the caller asked. A NULL fact never matches (fail-closed), so a criterion on a sparse facet is honestly narrow rather than wrong. The one exception is `req.title_excludes`, which vetoes and therefore does NOT fire on an absent title -- an unknown fact cannot prove an exclusion either. POST rather than GET because criteria is a nested object; a URL-encoded AND-of-ORs would be an invented serialization, which is the open grammar the closed vocabulary exists to refuse. Rows carry the normalized req layer no other route serves -- skills, seniority, job family, declared **and** inferred compensation (with `salary_estimate_samples`, so an estimate can be judged rather than trusted), the eligibility block, apply actionability, lifecycle and dedup -- plus `req_key`, the ledger's own identity for the req, so a page joins to `/v1/events`. `salary_min_usd` and `salary_max_usd` are the pay band: either alone is half-open, both together bracket one comparable yearly-USD figure per row. That figure is the employer's declared salary when there is one (the midpoint of a declared range) and our inferred median otherwise, and the inferred one qualifies only above a sample floor -- so a band is never satisfied by a thinly-evidenced guess, and never half by the employer's number and half by ours. A req with no salary at all matches no band (fail-closed), and an inverted band is a 422 rather than a confidently empty page. `exclude_agencies` (default true) removes staffing agencies, aggregators and job boards, so a row names the employer. `live_only` (default true) keeps expired and superseded postings out. Keyset-paginated: pass the previous page's `next_cursor`, which is monotone, so it doubles as "everything new since my last call". `limit` is bounded -- this endpoint meters the billed `source_row` atom off its own serialized rows, so an out-of-range page is a 422 rather than a silent truncation.

Flat, role-granular job search: the individual open roles across companies matching `role` (function) / `geo` (country) / `since` (first-seen lower bound), one row per logical req. ATS-only, freshness-floored, PK-ordered and keyset-paginated via the opaque `next_cursor` (the page's last `company_id:req_key`). The company-granular reverse view is `/v1/reqs/search`; full multi-board dedup for one company is `/v1/companies/{company_id}/open-reqs`. `industry`, `industry_terms` and `headcount_band` cut the corpus down to your ICP's companies. Repeat a parameter to OR its values; different parameters AND. They are filters only -- no company facet is added to a served row by passing one -- and a company whose fact we do not hold is never matched, so a cut is honestly narrow rather than quietly padded. `q` is free-text title search, ranked: it expands semantically to nearby job titles and matches them against the posting's own title, and each row carries the `relevance` (0-1) it scored. `sort` picks the ordering -- 'relevance' (the default whenever `q` is given) or 'recency'. Omit both and the page keeps its shipped stable order exactly. `q` is INDEPENDENT of `role`: pass both to search titles within one function. An unresolvable `role` -- anything that is not a function taxonomy id -- is rejected with 422 instead of returning a silently-empty result. `limit` is bounded: an oversized page is rejected with 422 rather than truncated -- page through the full set with `next_cursor` instead of raising `limit`. The shared public demo key gets a tighter page instead -- it bills nothing, so no ledger-derived gate can bound it, and a full-size page would make a world-readable credential a bulk-export window onto the fresh index. `sort='relevance'` without a `q`, and a `next_cursor` replayed under a different `sort`, are 422s for the same reason: an order other than the one asked for reads as a measurement.

One open role, addressed by the `(company_id, req_key)` pair every `/v1/jobs/search` row carries -- the follow-up call for a role you already hold an identifier for, instead of re-pulling the whole company through `/v1/companies/{company_id}/open-reqs`. Scoped exactly as `/v1/jobs/search` is: ATS-only and freshness-floored, one row per logical req. The body adds `raw_title` (the posting's own title) and `boards` -- the full, deduped list of boards reporting this req, which a search page cannot afford per row. A req that does not exist, is closed, or has not reached the freshness floor is a 404, never an empty 200 -- and a 404 is not metered.

The earliest first-in-function event per function -- detects a new budget line. Sourced from the role-slot recompute aggregate, not a specific board posting; `source_board` says so honestly rather than being excluded outright. Free-tier reads are history-capped. An unresolvable `function` -- anything that is not a function taxonomy id -- is rejected with 422 instead of returning a silently-empty result.

Hard-to-fill reqs by repost count, hardest first -- ATS-only, freshness-floored. Free-tier reads are history-capped.

A company's ATS-vendor switches -- ledger-backed, with a provenance-wrapped `occurred_at`. No ATS-only filter needed: ATS platform accounts have no LinkedIn dimension.

Market-wide (no single-company scope) active-req demand series for `role` / `geo` -- ATS-only by construction. An unresolvable `role` -- anything that is not a function taxonomy id -- is rejected with 422 instead of returning a silently-empty result.

The motion atoms + history primitives pre-joined into one bounded, compact call -- an agent's whole pre-action context in one round-trip instead of five. Honors `max_age` (seconds); cold returns `202 {job_id, status: "crawling"}`, same as hiring-pulse.

The `since=cursor` diff feed -- ledger events with `event_seq > since`, ordered ascending, plus a `next_cursor` an agent replays instead of polling or re-scraping. Meters one `change` unit per event RETURNED, independent of poll count: an empty page costs nothing. A free-tier caller is change-feed-gated to the same freshness floor every other free atom uses. `limit` is bounded: an oversized page is rejected with 422 rather than truncated -- replay with `next_cursor` instead of raising `limit`.

Register a webhook delivery target -- `secret` is stored as the endpoint's HMAC signing key, scoped to the caller's own customer, and never logged. Idempotent on (customer, url): re-registering the same target returns the SAME id rather than a second row, so a retrying caller ends up with one endpoint it can hand straight to `POST /v1/watches`. Omitted `secret` is generated server-side.

Subscribe to hiring events on a registered webhook -- scoped to the caller's own customer: `webhook_endpoint_id` must belong to the same customer. Meters one `watch` unit. The watch covers one company (`company_id`) or a saved search (`criteria`) -- exactly one, and a criteria outside the closed vocabulary is a 422 raised before any row is written. A free key holds a limited number of watches AT ONCE; the one past that is a 402 carrying the upgrade path, checked before the watch is created, so a walled call leaves no subscription behind. Cancelling a watch returns the slot.

The caller's own live watches -- what is currently subscribed on their customer, newest first, canceled ones excluded. A "Watch this search" signup lands with a watch already installed, and this is where its owner confirms what it watches and which endpoint it delivers to. Not billable, like the other self-serve introspection reads (`/webhook-deliveries`): reading your own subscriptions is account management, not metered corpus access. Each watch also reports `fires_last_hour` against its declared `max_fires_per_hour`, and `rate_limited` when the two have met: fires past that cap are DROPPED rather than queued, so this is the only place a saturated watch can be told from a quiet one. And each reports its heartbeat -- `last_fired_at`, `fires_last_7d`, `fires_last_30d` and a one-word `status` -- so a watch that is silent because nobody is hiring reads differently from one that is silent because its criteria can never match, its plan stopped it, or its endpoint is down. Absence is the customer's only evidence a watch is mis-specified, and for a metered product it is also the receipt for the months where the honest answer is "nothing matched".

Cancel a watch, scoped to the caller's own customer -- canceling another tenant's watch id 404s, identical to canceling one that doesn't exist (fail-fast, mirrors `delete_key`). Canceling one's own already-canceled watch is a 204 no-op, so the verb stays idempotent.

The caller's own self-serve webhook delivery log -- every delivery for their own customer, most recent first. Each entry carries the `idempotency_key` the delivery was sent with (also its `X-Plane-Idempotency-Key` header, and the id of the billed unit on your invoice) plus the `response_status` your endpoint returned, so a charge can be matched to the delivery that earned it without a support thread. A NULL `response_status` means we observed no HTTP response: the delivery has not been attempted yet, the connection failed outright, or it was mailed to a hosted-email endpoint.

One delivery's detail, scoped to the caller's own customer.

Reopens a webhook delivery for the next dispatcher tick to redeliver -- a self-serve replay debugger. Scoped to the caller's own customer, idempotent, and within the replay SLA window.

Write back a conversion outcome for `company_id`. Appends to the caller's own outcome labels, which are retention-protected.

"Signal #N -> you won." -- the caller's own outcome labels joined back to the signals this plane actually delivered them. A label for a company we never signalled is deliberately absent: this is an attribution view, not a label dump. `attributed_14d` counts the ones that landed in the last 14 days.

The calibrated-intent score + coverage meter for `company_id` -- computed live off every customer's submitted outcome labels. `score` is `None` below the coverage-gating minimum (never a fabricated number).

Turn a website or a company name into the `company_id` every company-scoped endpoint takes. Pass exactly one of `domain` or `name`; both or neither is a 422 naming that rule. A domain returns the companies registered at it; a name returns up to five candidates, each with a `match_confidence` -- 1.0 for an exact name, 0.8 for a match once legal suffixes are dropped. Each company carries its `country_code` and `coverage_status`, and no hiring signal -- ask `/v1/companies/{company_id}/is-hiring` for that. Nothing matching is an empty array, never a 404. Not billable.

Clay HTTP-provider hiring-motion enrichment column -- entity-resolves `domain`/`name` to a company via the local plane cache, then composes company enrichment and hiring pulse into a flat, Clay-column-shaped response: no field beyond this declared model ever leaks, every field is ATS-only and provenance-backed by its own primitive. Metered to the presented (Clay account) key. A miss is a 200, not a 404: a 404 blanks the Clay cell, which the customer reads as "not hiring". It carries `coverage_status`, a `message`, a `checked_at` -- and NULL motion fields, never zeros. The call still meters.

Migration import from an incumbent: a switcher's uploaded Coresignal/Apollo company list, resolved to the panel and enriched with the hiring-motion column; every miss is routed to a real coverage request, so switching cost drops to near zero without a second "please crawl this" mechanism. Not billable -- same convention as `/quickstart` and `/onboarding`.