Check resources and writes

List and read

GET /checks relative to /api/v1 / MCP list_checks. Requires checks:read; supports limit/cursor and:

Query	Values
q	Name search, string up to 255 characters
kind	ping, website, dns, tcp, domain, ssl_certificate
status	pending, up, late, down, paused, degraded

GET /checks/:id / MCP get_check requires checks:read and the returned check ID. Both return safe check resources:

{
  "id": "check_EXAMPLE",
  "status": "pending",
  "configuration": {
    "name": "Public website",
    "kind": "website",
    "url_configured": true,
    "interval_seconds": 3600,
    "degraded_threshold": null,
    "failing_threshold": 1,
    "expected_status_code": 200,
    "follow_redirects": false
  },
  "notification_group_ids": [],
  "dashboard_ids": []
}

The example ID is a placeholder; use actual response IDs. Configuration contains fields for that kind. Website URLs are deliberately omitted; the url_configured boolean is not a recoverable URL.

Create and update

POST /checks / MCP create_check: requires checks:create, check object, and idempotency. Name and kind are required.

PATCH /checks/:id / MCP update_check: requires checks:update, ID and check object. Supply only changed supported fields. Kind cannot change. Unknown fields and fields belonging to another kind are rejected.

{
  "check": {
    "name": "Renamed website",
    "interval_seconds": 3600
  }
}

Common and association inputs

Field	Constraint
name	Nonempty string, at most 255 characters
kind	One of the six kind strings; required on create, immutable afterward
notification_group_ids	Up to 100 unique existing account group IDs; requires notification_groups:assign
dashboard_ids	Create only; up to 100 unique existing custom dashboard IDs; requires dashboards:assign

Omitting an association preserves it on update. An empty group array clears group assignments. Dashboard membership changes after creation use the assignment operations, not dashboard_ids on update.

Heartbeat fields

Field	Accepted / default
schedule_type	interval (default) or cron
interval_seconds	Positive integer, required for interval; no API-created interval default
cron_expression	String up to 255 or null; required and valid for cron
timezone	Known timezone string up to 255; default UTC
grace_period_seconds	Integer >=0; default zero
degraded_threshold	Positive integer or null; default null requires all
failing_threshold	Positive integer; default one
value_direction	above, below or null
value_warning_threshold	Number or null
value_critical_threshold	Number or null

Value thresholds must be supplied together. Critical is greater than warning for above, less for below; comparisons include equality.

Website fields

Field	Accepted / default
url	Required nonempty public HTTP/HTTPS URL, at most 4096 characters
interval_seconds	Required positive integer at or above plan floor
expected_status_code	Integer 100-599; default 200
follow_redirects	Boolean; default false
degraded_threshold, failing_threshold	Quorum as above

DNS fields

Field	Accepted / default
hostname	Required valid ASCII DNS name, up to 255 characters at schema level
dns_record_type	Required A, AAAA, CNAME, MX, TXT, NS or CAA
dns_match_mode	resolves, exact or includes; when omitted, includes for A/AAAA/TXT and exact otherwise
dns_expected_values	Array of up to 100 strings, each up to 4096 characters; model also enforces byte limits; required nonempty for exact/includes
interval_seconds	Required positive integer at or above plan floor
degraded_threshold	null/all-three or integer 1-3
failing_threshold	Integer 1-3; default two

Use a JSON array, not the UI’s line-separated dns_expected_values_text. See DNS normalization and propagation.

TCP fields

Field	Accepted / default
hostname	Required valid bare hostname
port	Required integer 1-65535
interval_seconds	Required positive integer at or above plan floor
degraded_threshold, failing_threshold	Quorum as above

Domain and certificate fields

Field	Accepted
hostname	Required bare valid hostname
renewal_warning_days	Required positive integer
renewal_critical_days	Required positive integer less than warning

Cadence is fixed hourly; these kinds do not accept configurable interval, cron or location quorum fields.

Schema validation and model validation both apply. A schema-valid body can still fail hostname, quota, cadence or cross-field checks. Integer cadence and day/count fields are bounded by 2,147,483,647 at the shared schema layer.

See errors for validation_failed and quota_exceeded. No API field configures probe regions, custom headers, check deletion or pause.