Update watch

From list_watches or create_watch.

false pauses the watch (skipped by matching + delivery); true resumes it.

Display name (e.g. 'M5 Mac mini'). Pass an empty string to clear it - the email digest then falls back to the query. Renaming never rebuilds the match set.

New query. Rebuilds the watch's match set.

New single-feed scope, from get_feeds. Pass null to widen back to all subscriptions; OMITTING it leaves the scope unchanged. Must be a feed you subscribe to: any other feed_id is refused with not_subscribed and nothing changes. Changing scope rebuilds the match set (rebackfilled_because 'scope').

New folder scope: limit to feeds in this subscription folder, spelled exactly as get_feeds returns it (not validated - a name no subscription uses matches nothing). Empty string widens back to all subscriptions. Changing scope rebuilds the match set (rebackfilled_because 'scope').

Semantic similarity cutoff in (0,1]; any value is settable. Changing it re-runs the backfill so matches reflect the new cutoff, and the response returns a fresh threshold_preview. Calibration: below ~0.45 is effectively unfiltered, 0.55-0.60 is on-topic, above 0.70 is near-exact.

Where matches are delivered: in_session = retrieved when you call get_watch_matches or get_new_articles; email = digest to the account email; webhook = POST to webhook_url. webhook_url is NOT checked here, unlike create_watch, which refuses delivery=webhook without one (webhook_url_required). Send one in the same call unless the watch already has one, or every send fails server-side with nothing surfaced to you. Speeding up delivery settles the matches that piled up under the slower setting rather than shipping them all at once — returned as settled_backlog, and they stay visible via get_watch_matches.

For email/webhook delivery: how often to send. weekdays = daily but Monday-Friday only (weekend matches ride Monday's digest); realtime = the next 15-minute delivery tick. Unlike create_watch there is no default - an unset cadence stays unset and sends daily. A cadence on an in_session watch schedules nothing and returns cadence_inert. Switching to a FASTER cadence settles the backlog the slower one accumulated (settled_backlog) — a watch moved from weekly to realtime sends the next match, not the week behind it.

Daily/weekly delivery hour, 0-23, account timezone. Default 8.

Weekly delivery weekday. Default monday.

The https:// endpoint we POST match batches to. Must be a public host - loopback, private and link-local addresses are rejected with invalid_webhook_url, and the whole update aborts, so no other field in the call is applied. Pass an empty string to clear it.

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.