---
title: "Update a monitor"
method: PATCH
path: "/monitors/{monitor_id}"
tags: ["Monitors"]
---

# Update a monitor

`PATCH /monitors/{monitor_id}`

Updates a monitor. If `target` or `change_detection` changes, the monitor creates a new baseline. Unsupported target/change detection combinations are rejected.

## Path parameters

- `monitor_id` string, required

## Request body

- MonitorsUpdateMonitorRequest — Shared monitor update fields. `target` and `change_detection` can be updated, but the final combination must be supported.
  - `name` string
  - `tags` string[] — User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.
  - `status` 'active' | 'paused'
  - `target` union — Discriminated union describing what the monitor watches.
    - MonitorsPageTarget — Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
      - `type` 'page', required
      - `url` string, uri, required
      - `instructions` string — Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
      - `normalize_whitespace` boolean — Normalize whitespace before comparing or analyzing text.
    - MonitorsSitemapTarget — Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. On a detected difference the sitemap is re-fetched within the same run and only URLs both observations agree on are reported, suppressing transient crawl flaps.
      - `type` 'sitemap', required
      - `url` string, uri, required — Sitemap URL to monitor.
      - `include` string[] — URL path patterns to include (max 50).
      - `exclude` string[] — URL path patterns to exclude (max 50).
      - `max_urls` integer — Maximum number of sitemap URLs to track (capped at 10,000).
    - object — Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged for relevance against the monitor's `instructions` (and `schema`, when provided). The tracked page set is refreshed by a periodic re-discovery crawl.
      - `type` 'extract', required
      - `url` string, uri, required — Root URL to extract structured data from.
      - `schema` object — JSON Schema describing the data you care about. It is used three ways: it guides which pages are selected for tracking, it gives the change judge extra context on which changes matter (alongside `instructions`), and it defines the shape of the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most about once a day). It is not a response format for changes: change events and webhook payloads always contain diffs, summaries, and evidence excerpts — never data in this schema's shape. If omitted, a default summary + key-points schema is used.
      - `instructions` string, required — Natural-language instructions guiding which pages and facts to track and which changes to report.
      - `max_pages` integer — Maximum number of pages to track.
      - `max_depth` integer — Optional maximum link depth from the starting URL (0 = only the starting page).
      - `follow_subdomains` boolean
  - `change_detection` union — Discriminated union describing how changes are detected.
    - MonitorsExactChangeDetection — Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
      - `type` 'exact', required
    - MonitorsSemanticChangeDetection — Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
      - `type` 'semantic', required
      - `confidence_threshold` number
  - `schedule` MonitorsSchedule — Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
    - `type` 'interval', required
    - `frequency` integer, required — Number of units between runs. The resulting interval (frequency × unit) must be at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; maximum 365 when unit is days).
    - `unit` 'minutes' | 'hours' | 'days', required
  - `webhook` MonitorsNullableWebhookConfig
    - `url` string, uri, required — Webhook URL events are delivered to.
    - `events` string[] — Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `["change.detected"]` when omitted.
    - `secret` string — Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=<unix>,v1=<hmac>` header, where the HMAC is SHA-256 over `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.

## Response `200`

Updated monitor

- MonitorsMonitor — A web monitor. `mode` is the constant `web`; behavior is described by `target` (page/sitemap/extract) and `change_detection` (exact/semantic).
  - `mode` 'web', required — Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.
  - `id` string, required
  - `name` string, required
  - `target` union, required — Discriminated union describing what the monitor watches.
    - MonitorsPageTarget — Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
      - `type` 'page', required
      - `url` string, uri, required
      - `instructions` string — Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
      - `normalize_whitespace` boolean — Normalize whitespace before comparing or analyzing text.
    - MonitorsSitemapTarget — Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. On a detected difference the sitemap is re-fetched within the same run and only URLs both observations agree on are reported, suppressing transient crawl flaps.
      - `type` 'sitemap', required
      - `url` string, uri, required — Sitemap URL to monitor.
      - `include` string[] — URL path patterns to include (max 50).
      - `exclude` string[] — URL path patterns to exclude (max 50).
      - `max_urls` integer — Maximum number of sitemap URLs to track (capped at 10,000).
    - object — Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged for relevance against the monitor's `instructions` (and `schema`, when provided). The tracked page set is refreshed by a periodic re-discovery crawl.
      - `type` 'extract', required
      - `url` string, uri, required — Root URL to extract structured data from.
      - `schema` object — JSON Schema describing the data you care about. It is used three ways: it guides which pages are selected for tracking, it gives the change judge extra context on which changes matter (alongside `instructions`), and it defines the shape of the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most about once a day). It is not a response format for changes: change events and webhook payloads always contain diffs, summaries, and evidence excerpts — never data in this schema's shape. If omitted, a default summary + key-points schema is used.
      - `instructions` string, required — Natural-language instructions guiding which pages and facts to track and which changes to report.
      - `max_pages` integer — Maximum number of pages to track.
      - `max_depth` integer — Optional maximum link depth from the starting URL (0 = only the starting page).
      - `follow_subdomains` boolean
  - `change_detection` union, required — Discriminated union describing how changes are detected.
    - MonitorsExactChangeDetection — Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
      - `type` 'exact', required
    - MonitorsSemanticChangeDetection — Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
      - `type` 'semantic', required
      - `confidence_threshold` number
  - `schedule` MonitorsSchedule, required — Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
    - `type` 'interval', required
    - `frequency` integer, required — Number of units between runs. The resulting interval (frequency × unit) must be at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; maximum 365 when unit is days).
    - `unit` 'minutes' | 'hours' | 'days', required
  - `webhook` MonitorsNullableWebhookConfig
    - `url` string, uri, required — Webhook URL events are delivered to.
    - `events` string[] — Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `["change.detected"]` when omitted.
    - `secret` string — Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=<unix>,v1=<hmac>` header, where the HMAC is SHA-256 over `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.
  - `status` 'active' | 'paused' | 'failed', required — Monitor lifecycle status. `failed` means the most recent run failed (see the monitor's `last_error`); failed monitors keep running on schedule and flip back to `active` on the next successful run. Monitors are auto-`paused` after repeated consecutive failures or insufficient-credit skips; resume by PATCHing status to `active`.
  - `last_run_at` string, date-time, nullable
  - `last_change_at` string, date-time, nullable
  - `next_run_at` string, date-time, nullable — When the next scheduled run is due.
  - `last_error` MonitorsRunError
    - `code` string, required
    - `message` string, required
  - `webhook_failure` MonitorsWebhookFailure
    - `consecutive_failures` integer, required — Number of consecutive delivery attempts that did not succeed.
    - `last_status` 'rejected' | 'failed' | 'skipped_unsafe_url', required — Outcome of the most recent failed delivery. rejected means a non-2xx response; failed means no HTTP response was received; skipped_unsafe_url means the URL failed the public-endpoint safety check.
    - `last_message` string, required — Human-readable description of the most recent failure.
    - `last_failed_at` string, date-time, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `tags` string[] — User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.
  - `baseline` union — Current baseline: the last observed value the monitor compares new snapshots against. Its shape follows `target.type` (page/sitemap/extract). Only populated on GET /monitors/{monitor_id}; null until the first baseline run completes (and after a target or change_detection update, which resets the baseline).
    - MonitorsPageBaseline — Current baseline of a `page` monitor: the visible page text as last observed.
      - `text` string, required — The page's visible text as last observed.
      - `captured_at` string, date-time, required — When this baseline was last captured or replaced.
    - MonitorsSitemapBaseline — Current baseline of a `sitemap` monitor: the normalized URL set as last observed.
      - `urls` string[], required — The sitemap URLs as last observed (sorted, normalized).
      - `url_count` integer, required — Number of URLs in the baseline.
      - `captured_at` string, date-time, required — When this baseline was last captured or replaced.
    - MonitorsExtractBaseline — Current baseline of an `extract` monitor: the pages it tracks and the structured data as last extracted.
      - `data` unknown, required
      - `urls_analyzed` string[], required — The page URLs the monitor tracks and analyzes for changes.
      - `captured_at` string, date-time, required — When this baseline was last captured or replaced.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/context/apis/context-dev.md) · [All operations](https://skmtc.net/context/apis/context-dev/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/context/context-dev/versions/3c6a01ba967f/schema)