REST API

Authentication

Create an API key under API keys with the scopes you need. Send it as a bearer token: Authorization: Bearer ugk_... Keys bound to a workspace act in that workspace. Account-wide keys must send X-Workspace-Id.

Scopes

monitors:read, monitors:write, incidents:read, incidents:write, metrics:read, status_pages:read, status_pages:write, notifications:read, notifications:write. Authorization rules are identical to the web application; a key can never do more than the person who created it.

Pagination

List endpoints return data, nextCursor and sometimes total. Pass cursor to fetch the next page; limit is 1 to 100.

Idempotency

Send Idempotency-Key on POST creates. The same key with the same body returns the stored response for 24 hours; the same key with a different body is rejected with 409.

Rate limits

600 requests per minute per key. Responses include X-RateLimit-Limit and X-RateLimit-Remaining; 429 responses include Retry-After.

Errors

Every error is {"error":{"code","message","details?","requestId?"}} with codes such as unauthorized, insufficient_scope, not_found, validation_error, quota_exceeded, feature_unavailable, rate_limited.

Specification

The OpenAPI 3.1 document is generated from the same validation schemas used at runtime: /api/v1/openapi.json.

Example

curl -X POST https://your-host/api/v1/monitors \
  -H "Authorization: Bearer ugk_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"http","name":"Marketing site","config":{"url":"https://www.example.com/"},"intervalSeconds":60}'