Watch a company or a saved search

Scope the watch with exactly one of company_id (one company) or criteria (a saved search).

event_types names which hiring events fire it, at least one of: opened (a req seen for the first time), reobserved (a known req seen again on a later day), reposted (a req that came back after it was gone) and closed (a req verified gone from its source). Any other value is a 422 and creates nothing.

One live watch, as its owner sees it (signalsapi-3963). criteria is echoed exactly as it was authored -- watch_criteria.parse() normalizes on the read side at fan-out, so the row is the customer's own text.

The three rate fields (signalsapi-4442) are what tell a CAPPED watch from a quiet one: without them a watch saturating its declared max_fires_per_hour -- whose excess fires are dropped, not queued -- looked byte-identical to one nobody is hiring against.

The four heartbeat fields (signalsapi-4443) answer the question one rung before that: a watch firing NOTHING was indistinguishable from one that is broken, wall-blocked, or matching a criteria set that can never match. last_fired_at is when it last matched anything (null if never) and status is one of watch_service.WATCH_STATUSES -- the one-word reason, never a boolean, because "upgrade the plan", "raise your own cap" and "fix your endpoint" are three different fixes that must not render the same.

POST /v1/watches returns this same shape (signalsapi-5505) rather than a bare {id} -- a fresh watch's health fields are well-defined (zero fires, not yet rate-limited) and a caller that wants to show the new watch immediately would otherwise have to round-trip GET /v1/watches for a response its own create call already has the data for.