Update a monitor
update_monitorIdempotent
Change the settings of one existing monitor while leaving its other fields as they are. Pass only the fields to modify; at least one field besides the monitor ID is required.
Instructions
Change one monitor's settings and return it in the get_monitor shape. Only the fields you pass change, and at least one besides monitor_id is required (422 otherwise); type and target never change (create a new monitor instead). Not for pausing or resuming (pause_monitor, resume_monitor), for many monitors at once (bulk_update_monitors) or for tags alone across monitors (bulk_update_monitor_tags). Requires a key with the write scope. Plan limits are checked against the result, as on create_monitor (only moving a monitor below 60 seconds takes a fast slot): breaking one is a 403 naming it. Port-list rules are checked against the result too, so changing only the interval or regions of a port-list TCP monitor can be a 422. Omit a field to keep it; never send null. Example: {"monitor_id": "", "interval_seconds": 600}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Display name, 1 to 255 characters. | |
| tags | No | Replaces the whole tag list when passed, at most 10; [] clears it; omit it to keep the tags. Each tag is trimmed, lowercased and deduplicated on write, at most 50 characters of a-z, 0-9 and : _ . / -, starting with a letter or digit. Reuse names from list_tags rather than inventing near-duplicates. | |
| config | No | Replaces the monitor's whole config, not just the keys you send: a field of the type's schema you leave out resets to its default (read the current one with get_monitor first). Sending only port on a TCP monitor whose expected_state is closed resets it to open. A port-list TCP monitor cannot switch to a single port (422). An object whose fields depend on type, all optional unless stated. HTTP: method (GET, HEAD, POST, PUT, PATCH or DELETE, any case; default GET); expected_status_codes (non-empty list of codes 100 to 599, default [200]); keyword (case-sensitive substring the body must contain, at most 1024 characters, not with HEAD); follow_redirects (default true); verify_ssl (default true; false skips TLS verification, so the monitor can never report TLS_INVALID); request_headers (object of name to value: at most 20, a name at most 128 characters of letters, digits and ! # $ % & ' * + - . ^ _ ` | ~, a value at most 1024 bytes of printable ASCII, space or tab, the whole object at most 8192 bytes as JSON; names differing only in case, and Host, Content-Length, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, CF-Connecting-IP or any Proxy-* name, are a 422); request_body (string, at most 8192 bytes as UTF-8, needs POST, PUT, PATCH or DELETE). Reads return every request_headers value as the literal __FETTLE_UNCHANGED__; writing that literal back in an update keeps the stored value (on create it is a 422). PING: packet_count (1 to 20, default 4). SSL: warn_before_days (1 to 365, default 14) and port (1 to 65535, default 443). TCP: either port (1 to 65535) with expected_state "open" (default) or "closed", or ports (1 to 20 distinct ports that must all be closed, which needs expected_state "closed", exactly one region and interval_seconds of at least 300; a check fails when any of them accepts a connection, and the monitor goes DOWN once confirmation_threshold failures confirm it). Both port and ports, or neither, is a 422; expected_state values are lowercase. DNS: record_type (A, AAAA, CNAME, MX, TXT or NS; required) and expected_value (at most 2048 characters). With expected_value one answer must equal it (case-insensitive, ignoring surrounding spaces and a trailing dot; exact for TXT); without it any answer passes. MX answers are the mail host names without priority (mail.example.com, not 10 mail.example.com). A and AAAA look up every address of the host, IPv4 and IPv6 alike, and any one may match; write an IPv6 address in its shortest form. | |
| regions | No | One or more distinct region codes, for example eu-central: the plan's choices are limits.allowed_regions in get_plan_usage. An unknown code, or more regions than the plan's max_regions, is a 403. SSL and DNS monitors take exactly one region (422 otherwise). | |
| monitor_id | Yes | The monitor's uuid from list_monitors. An id that is not a monitor of this organization, or a deleted one, is a 404. | |
| channel_ids | No | Notification channel uuids from list_channels. When passed it replaces the whole binding; [] clears it, after which every verified, active channel is alerted; omit it to keep the binding. An id that is not an active channel of this organization is a 404. | |
| badge_enabled | No | Turns the monitor's public status badge on or off. A monitor on a published status page has a badge even when it is false. | |
| timeout_seconds | No | Seconds one check may take before it fails, 1 to 120. | |
| interval_seconds | No | Seconds between checks, 30 to 86400. The plan sets a minimum (limits.min_interval_seconds) and caps how many monitors may check more often than every 60 seconds (max_fast_monitors); breaking either is a 403 naming the limit. | |
| confirmation_threshold | No | How many checks in a row must fail in every region before the monitor goes DOWN and an incident opens, 1 to 10; 3 when not set on create. | |
| notification_cooldown_seconds | No | 60 to 86400 seconds; 1800 when not set on create. Only holds back a duplicate first alert for the same incident within that window. Repeat reminders while an incident stays open and unacknowledged follow the plan's renotify_interval_seconds and renotify_max_count (get_plan_usage; 0 means no reminders) instead, and the recovery alert is never held back. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | Yes | ||
| tags | No | ||
| type | Yes | Known values: HTTP, PING, SSL, TCP, DNS. | |
| config | Yes | ||
| status | Yes | Known values: PENDING, UP, DEGRADED, DOWN, PAUSED. | |
| target | Yes | ||
| regions | Yes | ||
| user_id | Yes | ||
| is_active | Yes | ||
| created_at | Yes | ||
| updated_at | Yes | ||
| channel_ids | No | ||
| next_run_at | Yes | ||
| badge_enabled | No | ||
| ssl_cert_info | No | ||
| ssl_expires_at | Yes | ||
| last_checked_at | Yes | ||
| region_statuses | Yes | Per-region latest status, sorted by region name. Built from ``region_snapshots``; ``job_id`` is dropped (internal dedup key) and malformed/partial snapshot rows are skipped rather than failing the read. | |
| timeout_seconds | Yes | ||
| interval_seconds | Yes | ||
| confirmation_threshold | Yes | ||
| notification_cooldown_seconds | Yes |