Conventions

These conventions apply to every resource in the API unless a resource page overrides them.

Identifiers

All resource IDs are ULIDs: 26-character base32-encoded 128-bit values, sortable by creation time. Example: 01HXABCFIREDBBBBBBBB. Paths always accept the ULID as the {id} segment.

Some resources also expose a human-readable slug for public-facing URLs (orgs, status pages). Slugs are immutable once set.

Timestamps

All timestamps are ISO 8601 / RFC 3339 UTC, including fractional seconds when present:

2026-04-24T17:42:03.417Z

Relative times (e.g. “last 24h”) are not accepted; compute the absolute bounds on the client.

Durations

Durations are specified as integer seconds in request bodies. Some query parameters accept 5m / 2h / 3d shorthand; the documentation for each endpoint calls this out.

Pagination

List endpoints return up to 50 items per page by default. Pass limit (max 200) and cursor to page through results:

GET /api/v1/monitors?limit=100&cursor=eyJwayI6IjAxSFg...

The response envelope wraps the data:

{
  "data": [ /* … */ ],
  "next_cursor": "eyJwayI6IjAxSFg...",
  "has_more": true
}

When has_more is false, next_cursor is absent. Cursors are opaque; do not parse them.

Filtering and sorting

Where supported, list endpoints accept:

• q: full-text search over a resource’s searchable fields.
• sort: a sortable field name, prefixed with - for descending (e.g. sort=-created_at).
• Resource-specific filters (e.g. status=firing on /alerts). Per-resource pages call these out.

Unknown query parameters are ignored for forward compatibility.

Partial updates

PATCH endpoints accept a partial document: only the fields you include are changed. To clear an optional field, send null:

{ "description": null }

PUT endpoints replace the resource wholesale. The distinction matters most on resources with collections-within-resources (e.g. escalation-policy steps, status-page layouts).

Idempotency

POST creation endpoints accept an Idempotency-Key header. If you retry a request with the same key within 24 hours, the server returns the original response instead of creating a duplicate. Use this on network-unreliable paths (e.g. deploy scripts triggering events).

Request limits

Limit	Default	Notes
Request body size	1 MiB	Ingest endpoints may lower this.
URL length	8 KiB
Batched CloudEvents array	256 events	Batched ingest endpoint.
Query parameter count	64

Dates and time zones

Server time is always UTC. The console renders timestamps in the viewer’s local time; API clients should do the same client-side. Scheduled features (maintenance windows, on-call rotations) accept a timezone field and handle DST automatically.

Character encoding

All string fields are UTF-8. Byte limits (when mentioned in per-resource schemas) count bytes, not runes; user-facing free-text fields use rune-aware truncation at the server.