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

# Create a monitor

`POST /monitors`

## Request

- Base URL: `https://api.domscout.io`
- URL: `https://api.domscout.io/monitors`
- Auth: API key in header `x-api-key`

A monitor is a standing instruction to capture a URL unattended on a schedule and report what changed. It carries the same API-key authentication and the same browser-execution gate as a capture, because it is a capture with a timer.

Plan ceilings: Hobby 0 monitors (403 PLAN_FEATURE_UNAVAILABLE), Pro 10 at a minimum interval of 60 minutes, Business 100 at 15 minutes, Enterprise 500 at 5 minutes. GET /credits reports availability under capabilities.routes["/monitors"].

Management calls are not billed. Each RUN reserves capture quota exactly as a scheduled check does, priced from the monitor's own captureParams.

If notifyWebhookUrl is set, the creation response carries notifyWebhookSecret. No API read returns it, so store it on receipt. Unlike an API key it is not unrecoverable: the account owner can reveal it in the dashboard, and POST /monitors/{monitorId}/rotate-secret replaces it, disclosing the replacement in that response.

## Request body

- object
  - `name` string, required
  - `targetUrl` string, uri, required
  - `intervalMinutes` integer: At least the plan minimum, at most 43200 (30 days).
  - `captureParams` object
  - `notifyWebhookUrl` string, uri, nullable: HTTPS only. Change notifications are signed with the secret returned at creation.
  - `checkMarkdown` boolean
  - `checkLinks` boolean
  - `checkTitle` boolean
  - `checkStatusCode` boolean
  - `checkDom` boolean
  - `domIgnoreSelectors` string[]
  - `domIgnoreAttributes` string[]
  - `domIgnoreTextPatterns` string[]
  - `domPositionTolerancePx` integer

## Response `201`

Created.

- object
  - `monitor` Monitor: A monitor as the API presents it. The signing secret is never included: only creation and rotation responses carry it, and no API read returns it. The dashboard can reveal it to the account owner.
    - `id` string, uuid
    - `name` string
    - `targetUrl` string, uri
    - `captureParams` object: The capture options every run uses. Restricted to an allow-list; injectJS is not among them, so a scheduled unattended render can never carry caller-supplied JavaScript.
    - `intervalMinutes` integer
    - `status` 'active' | 'paused'
    - `checks` object
      - `markdown` boolean
      - `links` boolean
      - `title` boolean
      - `statusCode` boolean
      - `dom` boolean
    - `domIgnoreSelectors` string[]
    - `domIgnoreAttributes` string[]
    - `domIgnoreTextPatterns` string[]: Checked for catastrophic backtracking at save time, because the worker applies them under a CPU budget on every run.
    - `domPositionTolerancePx` integer
    - `notifyWebhookUrl` string, uri, nullable
    - `lastRunAt` string, date-time, nullable
    - `lastRunStatus` string, nullable
    - `nextRunAt` string, date-time, nullable
    - `consecutiveErrors` integer
    - `createdAt` string, date-time
    - `updatedAt` string, date-time, nullable
  - `notifyWebhookSecret` string: Present only when notifyWebhookUrl was set. No API read returns it; the account owner can reveal it in the dashboard.
  - `notifyWebhookSecretNote` string: Present with notifyWebhookSecret and explains its one-time disclosure.

## Other responses

- `400`: Validation failed.
- `403`: Plan ceiling, or a platform hold.
- `429`: Rate or quota wall.
- `503`: A dependency this request needs is unavailable or not configured for this deployment. Codes: SUPABASE_TIMEOUT and SUPABASE_INVALID_RESPONSE (a storage operation did not answer, or answered unreadably — the write may have committed, so any retry must be idempotent), CAPTURE_ARTIFACT_UNAVAILABLE and CAPTURE_ARTIFACT_CORRUPT (a stored artifact could not be read or parsed), ASYNC_JOBS_NOT_CONFIGURED and CAPTURE_RETRIEVAL_NOT_CONFIGURED (the capability is not configured here, on any plan). Retryable unless the code names a deployment configuration.

---

[API](https://skmtc.dev/domscout/apis/domscout-api.md) · [All operations](https://skmtc.dev/domscout/apis/domscout-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domscout/apis/domscout-api/revisions/20562d5b5d94?raw)