create_monitor

sh.fettle/mcp · Verify this server

Create a monitor that checks a URL, host or port on a schedule and return it (the get_monitor shape). Requires a key with the write scope. Required: name (1 to 255 characters), type (HTTP, PING, SSL, TCP or DNS), target, interval_seconds, timeout_seconds and regions. target (up to 2048 characters): for HTTP an http:// or https:// URL (https:// is added when the scheme is missing; port, path and query are kept); for PING, SSL, TCP and DNS a bare public hostname or IP address with no :port and no path (the TCP or SSL port goes in config; host:port is a 422, while a full URL such as https://host:8443/x is cut down to its host and its port is lost). Hostnames must be ASCII (punycode for internationalized domains). localhost, *.localhost and IP addresses that are not public (private, loopback, link-local, CGNAT 100.64.0.0/10, reserved or unspecified) are rejected with a 422. type and target cannot be changed later. config is a JSON object whose shape depends on type. HTTP takes method (GET, HEAD, POST, PUT, PATCH or DELETE, any case; default GET), expected_status_codes (a non-empty list of codes 100 to 599, default [200]), keyword (case-sensitive substring the response body must contain, at most 1024 characters; not allowed with HEAD), follow_redirects (default true), verify_ssl (default true; false skips TLS verification, which also means that monitor can no longer report a TLS_INVALID failure), request_headers (an object of header name to value: at most 20 headers; a name is at most 128 characters of letters, digits and ! # $ % & ' * + - . ^ _ ` | ~; a value is at most 1024 bytes of printable ASCII, space or tab; the whole object at most 8192 bytes as JSON; two names differing only in case, and the reserved names Host, Content-Length, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, CF-Connecting-IP and any Proxy-* name, are a 422) and request_body (a string of at most 8192 bytes as UTF-8; requires POST, PUT, PATCH or DELETE), all optional. Reads never return request_header values: each one comes back as the literal __FETTLE_UNCHANGED__, and writing that value back in an update keeps the stored header unchanged (on create it is a 422). PING takes packet_count (1 to 20, default 4), optional. SSL takes warn_before_days (1 to 365, default 14) and port (1 to 65535, default 443), both optional. TCP takes either port (one port, 1 to 65535, expected_state "open" by default or "closed") or ports — a list of 1 to 20 distinct ports that must all be closed: ports requires expected_state "closed", exactly one region and interval_seconds of at least 300, and a check fails when any listed port accepts a connection (the monitor goes DOWN once confirmation_threshold failures confirm it). Passing both port and ports, or neither, is a 422. expected_state values are lowercase. DNS requires record_type (A, AAAA, CNAME, MX, TXT or NS; no default) and takes optional expected_value (at most 2048 characters): when set, one answer must equal it (case-insensitive, ignoring surrounding spaces and a trailing dot; exact for TXT); when absent, any answer passes. For MX the answers are the mail host names only, without priority (mail.example.com, not 10 mail.example.com). A and AAAA both look up every address of the host, IPv4 and IPv6 alike, and any one of them may match; write an IPv6 address in its shortest form. Omit config for HTTP, PING or SSL to use their defaults; omitting it on a TCP or DNS monitor is a 422. regions is a list of one or more distinct region codes (get_plan_usage lists them in limits.allowed_regions, for example eu-central; an unknown code is a 403) — SSL and DNS monitors must target exactly one region (422 otherwise). interval_seconds (integer, 30 to 86400) is the time between checks; timeout_seconds (integer, 1 to 120) is how long one check may take. confirmation_threshold (integer, 1 to 10; 3 when not set on create) is how many checks in a row must fail in every region before the monitor goes DOWN and an incident opens. notification_cooldown_seconds (integer, 60 to 86400; 1800 when not set on create) only holds back a duplicate first alert for the same incident within that window. Repeat reminders while the incident stays open and unacknowledged follow the plan's renotify_interval_seconds and renotify_max_count (see get_plan_usage; 0 means no reminders), not this value; it never holds back the recovery alert. Plan limits apply: monitor count, minimum interval_seconds, how many monitors may use an interval below 60 seconds, and max_regions per monitor. Breaking one is a 403 that names the limit (more regions than the plan allows is a 403 too; SSL/DNS with more than one region is a 422). get_plan_usage shows the limits and current usage. is_active (boolean, default true): false creates it paused — no check runs until resume_monitor; a paused monitor still counts toward the plan's monitor limits. channel_ids (array of channel uuids) binds notification channels; omit it or pass an empty list to alert every verified, active channel of the organization; an id that is not an active channel of this organization is a 404. list_channels gives the ids. tags is an optional list of flat labels (for example env:prod, service:api) used to group and filter monitors, at most 10 per monitor. Tags are trimmed, lowercased and deduplicated on write, each at most 50 characters of lowercase letters, digits and : _ . / - , starting with a letter or digit. Call list_tags first to reuse the organization's existing names instead of inventing near-duplicates. Other errors: 422 for an invalid argument, naming it. To create many monitors at once, use bulk_create_monitors. Example: {"name": "API", "type": "HTTP", "target": "https://api.example.com/health", "interval_seconds": 300, "timeout_seconds": 10, "regions": ["eu-central"], "config": {"expected_status_codes": [200]}, "tags": ["env:prod"]}