Requests, pagination and idempotency

Use JSON request bodies with Content-Type: application/json. Check writes use {"check":{...}}; dashboard writes use {"dashboard":{...}}. Unknown body/query fields are rejected, not silently ignored.

Identifiers and lists

Treat IDs as opaque strings. Check/dashboard IDs are prefixed identifiers; some other resources and history-source IDs are numeric strings. Use values returned by the API rather than converting or constructing IDs.

List responses use:

{
  "items": [],
  "next_cursor": null
}

Parameter	Default	Accepted
limit	20	Integer 1-100
cursor	0	Nonnegative integer returned as next_cursor

Results are paged in increasing underlying ID order. A cursor is not an offset, timestamp or prefixed resource ID. Continue until next_cursor is null. Dashboard detail nests this envelope under checks.

Results

Single-resource results are direct JSON objects, not wrapped in data. Successful creates return 201; ordinary reads/updates/assignment operations return JSON on success. A saved pending check is not verified target health.

Timestamps use ISO 8601. Measurement absence is null, not zero. Check reads omit the website URL and use url_configured instead because URLs can contain credentials. Incident reads omit causes, notes and delivery details. Heartbeat URL access is explicitly sensitive.

Creation retries

Check and dashboard creates require an Idempotency-Key header: a nonempty string of at most 100 characters. Use a unique key per intended creation.

Identical canonical creation arguments under the same grant/key reuse the created resource while the request record is retained. Different arguments produce idempotency_conflict. Keys share the grant’s creation-request namespace, so use different keys for different resource creations.

Request records older than seven days are removed; do not rely on a key forever. Replaying a deleted resource can fail, and replaying a dashboard that is no longer private can be forbidden. Replays return the current serialized resource, not an immutable copy of its original response.

MCP uses an idempotency_key argument, not an HTTP header. For transport failures, retry the same intended create with the same key; do not automatically issue a new create key.

See errors and rate limits before implementing retries.