Create watch

What to watch for. For keyword watches: an exact phrase — words must appear adjacent and in order, so write it like a headline ('OLED iPad mini', not 'iPad mini OLED'). For semantic watches: a natural phrase describing the topic/product (order-insensitive).

Optional display name (e.g. 'M5 Mac mini'). Returned as-is by list_watches, watch_summaries and matched_watches - null when unset, with no fallback there. Only the email digest substitutes the query when the label is empty.

keyword (default, all plans) or semantic (Max only — matches by meaning). Semantic on a non-Max account returns max_required.

Optional: limit to one feed. Omit for all subscriptions.

Optional: limit to feeds in this subscription folder. Omit for all subscriptions.

Semantic only: cosine similarity cutoff in (0,1]. Any value is settable — this is a dial, not a set of presets. Calibration from real data: below ~0.45 is effectively unfiltered (it sits under the median similarity of arbitrary articles and will match thousands); 0.55-0.60 is on-topic; above 0.70 is near-exact and starts missing paraphrases. The useful band is narrow and near the top. Default 0.55. The response includes threshold_preview — how many of this watch's matches each stricter cutoff would leave — so pick the next value from that rather than guessing.

Where matches are delivered. in_session (default) = retrieved when you call get_watch_matches or get_new_articles. email = digest to the account email. webhook = POST to webhook_url. email and webhook default to a daily cadence when none is passed.

For email/webhook delivery: how often to send. weekdays = daily but Monday-Friday only (weekend matches ride Monday's digest). Defaults to daily when delivery is out-of-band.

Daily/weekly email or webhook delivery: hour of day to send, 0-23, in the account's timezone ('email me daily at 7am' → 7). Default 8 (08:00).

Weekly cadence only: weekday to send ('weekly on friday'). Default monday.

Required when delivery='webhook': an https:// endpoint we POST match batches to. Must be a public host — loopback, private and link-local addresses are rejected.

Optional human-readable name. Returned as-is and null when unset; only the email digest substitutes the query.

Optional scope to one feed.

Optional scope to a subscription folder.

Semantic only: cosine similarity cutoff.

Digest delivery hour in the account's timezone; null = default 08:00.

Weekly digests: weekday name; null = default monday.

create: in-window articles that already matched.

update: match count after an edit that rebuilt the set.

update: which edit rebuilt the match set.

update: present when the edit emptied a watch that previously had matches - usually an over-narrow edit.

update: a cadence was set on an in_session watch, where it schedules nothing.

update: pending matches settled rather than emailed when delivery is sped up (in_session to email, or to a faster cadence), so the first digest is not the slower setting's backlog. Still readable via get_watch_matches.

update: accompanies settled_backlog - what was dropped from email and where it is still readable.

Set instead of a watch when the call was refused: max_required (semantic on a non-Max plan), invalid_webhook_url (not https, or a loopback/private/link-local host), watch_limit_reached, embedding_failed.