---
title: "Create a monitor"
method: POST
path: "/monitors"
tags: ["Monitors"]
---

# Create a monitor

`POST /monitors`

Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline.

## Request body

- MonitorsCreateMonitorRequest — Creates a web monitor. `mode` is the constant `web`; the behavior is described by `target` (page, sitemap, or extract) and `change_detection` (exact or semantic). Supported combinations: page + exact, sitemap + exact, extract + semantic.
  - `mode` 'web' — Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.
  - `name` string, required
  - `target` union, required — Discriminated union describing what the monitor watches.
    - MonitorsPageTarget — Watch a single web page.
      - `type` 'page', required
      - `url` string, uri, required
      - `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.
      - `exclude` string[] — URL path patterns to exclude.
      - `max_urls` integer — Maximum number of sitemap URLs to track (capped at 10,000).
    - MonitorsExtractTarget — 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 against the monitor's instructions. 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 guides which pages are selected for tracking and gives the change judge context on what matters. 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 the extracted data, ignoring cosmetic or paraphrase-only differences. What is watched is determined by the extract target's `schema` and `instructions`.
      - `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 called when a change is detected.
    - `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.
  - `tags` string[] — User-defined tags for grouping and filtering monitors and their changes.

## Response `201`

Monitor created

- 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.
      - `type` 'page', required
      - `url` string, uri, required
      - `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.
      - `exclude` string[] — URL path patterns to exclude.
      - `max_urls` integer — Maximum number of sitemap URLs to track (capped at 10,000).
    - MonitorsExtractTarget — 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 against the monitor's instructions. 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 guides which pages are selected for tracking and gives the change judge context on what matters. 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 the extracted data, ignoring cosmetic or paraphrase-only differences. What is watched is determined by the extract target's `schema` and `instructions`.
      - `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 called when a change is detected.
    - `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
  - `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.
  - `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
- `403` — Monitor limit for the account's plan reached (error_code MONITOR_LIMIT_EXCEEDED)

## Changes

- **2026-07-09** `de91b92d5fb7` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/context/apis/context-dev/changes/monitors/post.md)

---

[API](https://skmtc.dev/context/apis/context-dev.md) · [All operations](https://skmtc.dev/context/apis/context-dev/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/context/context-dev/revisions/de91b92d5fb7/schema)