Everything the interface does, the API does.

One REST API at https://app.upfour.io/v1 — 233 endpoints, the same ones the product itself runs on. This page is the contract: how requests are shaped, how they fail, and what we promise not to break. Every reference page has a “Try it” panel that runs real requests from your browser with your own key.

Authentication

Create an API key in the app under Settings → API tokens and send it as a Bearer token. Live keys start with pls_live_, test keys with pls_test_ — test keys operate on your sandbox organization, so you can experiment without touching production monitors. Keys carry fine-grained scopes such as monitor.read, monitor.write, incident.write and webhook.write; each endpoint below names the scope it needs.

curl -s https://app.upfour.io/v1/me \
  -H "Authorization: Bearer $UP4_API_KEY"

Response envelope

Successful responses wrap their payload in a flat envelope; lists add cursor metadata:

{ "data": { "id": "…" } }

{
  "data": [ … ],
  "pagination": {
    "cursor": null,
    "next_cursor": null,
    "prev_cursor": null,
    "limit": 50,
    "has_more": false
  }
}

Errors

One shape across all 4xx and 5xx responses — sanitized, with a request id you can send us:

{
  "error": {
    "code": "permission_denied",
    "message": "API token does not have the required scope",
    "request_id": "req_…"
  }
}

Pagination

List endpoints use signed keyset cursors, not page numbers. Pass limit (max 250) and follow pagination.next_cursor. Cursors expire after 24 hours and are bound to their sort and filters; the errors are stable: cursor_invalid, cursor_expired, cursor_parameters_changed.

Idempotency

Send Idempotency-Key on mutating requests. Replaying the same key with the same body returns the stored response with Idempotency-Status: replayed; the same key with a different body returns 409 idempotency_key_conflict. Stored for 24 hours.

Versioning

The URL version is /v1 and additive changes land there. Breaking changes would require /v2, 12 months of parallel support and Sunset/Deprecation headers. X-API-Version pins compatible behavior; keys remember their default version.

Rate limits

Every response tells you where you stand:

Buckets are per token for authenticated calls, per IP for unauthenticated ones, per slug for heartbeat pings.

Conventions

IDs are UUIDs. Timestamps are RFC 3339 in UTC. Boolean query values are a strict true or false. Browser API calls use Authorization, Idempotency-Key and X-API-Version. Documentation and marketing origins are bearer-only CORS origins and never receive credentialed session access; only the exact app origin may send the product's HttpOnly session cookie.

Machine-readable

The whole contract as files — generated from the same route inventory that gates our releases, so they cannot drift from production: OpenAPI 3.1 (YAML) · OpenAPI 3.1 (JSON) · Postman collection. For AI tooling there is an llms.txt index of every docs page.

Reference