---
title: "Create a watch"
method: POST
path: "/api/v1/watches"
---

# Create a watch

`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`

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.

## Request body

- object
  - `target_type` 'event' | 'area' | 'site', required: "event", "area" or "site".
  - `event_id` string, uuid: The signal’s id (uuid; required for "event").
  - `bbox` number[]: [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_id` string, uuid: Site: a registry facility id (from GET /api/v1/entities/search). Its coordinates are used; lat/lon are ignored.
  - `lat` number: Site: latitude of any point (when no entity_id).
  - `lon` number: Site: longitude of any point (when no entity_id).
  - `scale` 'facility' | 'city' | 'country': Site: how wide to look — "facility" (default), "city" or "country".
  - `radius_m` integer: 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_code` string: Site, country scale: ISO 3166-1 alpha-2. Resolved from the point when omitted.
  - `metric` string: Site: what to measure from imagery (a monitoring metric such as "ship_detection", "vv", "ndvi"), or "none". Omit for the suggested measurement.
  - `measure` boolean: Site: false to follow reporting only (same as metric "none").
  - `name` string: Label for the watch.
  - `notify_email` boolean: Email on meaningful changes (default false).
  - `imagery_alerts` boolean: 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 `201`

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

- object
  - `watch` object
  - `already_existed` boolean
  - `measurement` object: Site watches: whether a measurement was created ({ created, metric, reason, metering }).

## Other responses

- `400` (unresolved $ref)
- `401` (unresolved $ref)
- `403`: Plan limit: no active watch slots left (pause or delete one, or upgrade) — or, for a site with an explicit metric, the plan does not include that satellite or has no measurement slot left.
- `429` (unresolved $ref)

---

[API](https://skmtc.dev/offnadir-delta/apis/off-nadir-delta-api.md) · [All operations](https://skmtc.dev/offnadir-delta/apis/off-nadir-delta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/offnadir-delta/apis/off-nadir-delta-api/revisions/5cf3f2bed5a2?raw)