Create a watch

Free to create. Adds a target to the Watchlist. Where the plan includes the collection section, a watched event’s imagery is then checked automatically at 1 token a day per watch, until before and after scenes are found or 14 days after the first report; a day without enough tokens is skipped and not charged, and on other plans imagery is not checked and nothing is charged. target_type "event": pass the signal’s id (uuid) as event_id — the server resolves and binds the CANONICAL event (never an article URL), so further reporting and even a later cluster merge stay on the same watch. target_type "area": pass a bbox — created as a saved bookmark; to measure something there use POST /api/v1/monitoring, to watch its events use POST /api/v1/standing-orders (both join the same watch automatically). target_type "site": watch a specific place for change — a registry facility (entity_id from GET /api/v1/entities/search) or any point (lat, lon) — at a scale: "facility" (radius 250 m–3 km; measured from imagery by default when the kind of facility has a suggested measurement, e.g. vessel counts for a port), "city" (radius 5–20 km; measured only when you pass a metric) or "country" (followed through reporting only; never measured). Linked events are reported with how they were linked (named / nearby / country). A refused explicit metric creates nothing; a refused default is reported in measurement.reason. Measuring uses a monitored-area slot and costs the same as POST /api/v1/monitoring. Active watches are plan-limited; re-adding an existing target returns the existing watch (200) instead of consuming a slot.

post/api/v1/watches

Request

  • Base URL: https://offnadir-delta.com
  • URL: https://offnadir-delta.com/api/v1/watches
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

target_type'event' | 'area' | 'site' required

"event", "area" or "site".

event_idstring uuid

The signal’s id (uuid; required for "event").

bboxnumber[]

[minLon, minLat, maxLon, maxLat] WGS84 (required for "area"), at most 100,000 km² — a larger box returns 400 invalid_input when creating (re-adding an existing area is allowed).

entity_idstring uuid

Site: a registry facility id (from GET /api/v1/entities/search). Its coordinates are used; lat/lon are ignored.

latnumber

Site: latitude of any point (when no entity_id).

lonnumber

Site: longitude of any point (when no entity_id).

scale'facility' | 'city' | 'country'

Site: how wide to look — "facility" (default), "city" or "country".

radius_minteger

Site: radius in metres, snapped to the scale's steps (facility 250/500/1000/2000/3000; city 5000/10000/20000). Defaults from the kind of facility.

country_codestring

Site, country scale: ISO 3166-1 alpha-2. Resolved from the point when omitted.

metricstring

Site: what to measure from imagery (a monitoring metric such as "ship_detection", "vv", "ndvi"), or "none". Omit for the suggested measurement.

measureboolean

Site: false to follow reporting only (same as metric "none").

namestring

Label for the watch.

notify_emailboolean

Email on meaningful changes (default false).

imagery_alertsboolean

Area and facility- or city-scale site watches: notify when a NEW scene covering this area is published (Sentinel-2 optical and Sentinel-1 SAR). Default false. It reports that a look is now possible — never what is in the scene. Free on every plan: no tokens, no LLM.

Response

The created watch (200 with already_existed=true when the target was already watched).

watchobject
already_existedboolean
measurementobject

Site watches: whether a measurement was created ({ created, metric, reason, metering }).

Changes

No recorded changes to this operation across all 1 revision of this API.