# API — the contract

> REST API for monitors, scheduled jobs, incidents, status pages and reports: keys with scopes, envelope, pagination, errors, idempotency and rate limits, plus every route.

Source: https://upfour.io/docs/api

One REST API at `https://app.upfour.io/v1` with 271 routes for monitors, scheduled jobs, incidents, status pages, alerting, on-call, playbooks, clients, teams, webhooks, reports and company settings. Managing API keys, billing and personal account settings stays in the signed-in app. This page summarizes how requests are shaped, how they fail and how changes are announced; each topic has its own page. 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. Every key starts with `pls_` and carries scopes such as `monitor.read` or `incident.write`; each endpoint names the scope it needs. A key cannot create or manage other keys. [API keys and scopes](https://upfour.io/docs/api/keys-and-scopes.md) has the details and the errors.

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

## Response envelope

Successful calls made with an API key return their payload as `{ "data": … }`; lists add a `pagination` object. See [responses and errors](https://upfour.io/docs/api/responses.md).

## Errors

Every 4xx and 5xx response is `{ "error": { "code", "message", "request_id" } }`, with `details` when there is more to say. Branch on the code. The [error catalogue](https://upfour.io/docs/api/errors.md) lists every code with its cause and fix.

## Pagination

`GET /monitors` pages with signed cursors (`limit` up to 250, `pagination.next_cursor`); the incident lists use `page` and `per_page`, and most other lists return everything at once. [Pagination](https://upfour.io/docs/api/pagination.md) has the parameters and the cursor errors.

## Idempotency

Send `Idempotency-Key` on `POST` and `PATCH` requests. The same key with the same body returns the stored response for 24 hours; the same key with a different body is `409 idempotency_key_conflict`. [Idempotency](https://upfour.io/docs/api/idempotency.md) lists what is and is not stored.

## Versioning

Every operation is served under `/v1`; there is no `/v2`, and the API sends no `Deprecation` or `Sunset` header. The [changelog](https://upfour.io/docs/api/changelog.md) records every change, with a filter for breaking ones, and [versioning](https://upfour.io/docs/api/versioning.md) says what `X-API-Version` does today.

## Rate limits

Authenticated calls are limited per key (1,200 requests per minute, bursts of 300) and per IP address (3,000 per minute). A `429` carries `Retry-After`. [Rate limits](https://upfour.io/docs/api/rate-limits.md) explains the headers and how to back off.

## Client scope

In agency mode, pass `client_id` or `all_clients=true` on list calls and `client_id` in request bodies. See [client scope](https://upfour.io/docs/api/client-scope.md).

## 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

Every route as files, generated from the router’s route inventory: [OpenAPI 3.1 (YAML)](https://upfour.io/api/openapi.yaml) · [OpenAPI 3.1 (JSON)](https://upfour.io/api/openapi.json) · [Postman collection](https://upfour.io/api/up4.postman_collection.json). Parameters are typed; most request bodies are open objects, and the field tables on the reference pages cover monitors, scheduled jobs and alert channels so far. For AI tooling there is an [llms.txt](https://upfour.io/llms.txt) index of every docs page.

## Reference

Monitoring

| [Monitors](https://upfour.io/docs/api/monitors.md) | The heart of the API: create, list, pause, resume and delete the things we check, as often as every ten seconds. | 28 endpoints |
| --- | --- | --- |
| [Monitor groups](https://upfour.io/docs/api/monitor-groups.md) | Folders for monitors — group fleets per project or per customer. | 6 endpoints |
| [Scheduled jobs (heartbeats)](https://upfour.io/docs/api/heartbeats.md) | Cron jobs and backups that must call in before a deadline. Silence becomes an incident. | 12 endpoints |
| [Scheduled job groups](https://upfour.io/docs/api/heartbeat-groups.md) | Folders for scheduled jobs. | 6 endpoints |
| [Resource metadata](https://upfour.io/docs/api/metadata.md) | Free-form key/value metadata on monitors and scheduled jobs — owner, playbook link, cost center. | 2 endpoints |

Alerting & response

| [Incidents](https://upfour.io/docs/api/incidents.md) | Open, acknowledge, comment, escalate, resolve. | 27 endpoints |
| --- | --- | --- |
| [Severities](https://upfour.io/docs/api/severities.md) | Your incident severity ladder (SEV1…), fully customizable. | 1 endpoints |
| [Severity groups](https://upfour.io/docs/api/severity-groups.md) | Group severities into reusable sets. | 1 endpoints |
| [Alert channels](https://upfour.io/docs/api/notification-channels.md) | Where alerts go: email, Slack, Telegram, PagerDuty and friends. | 6 endpoints |
| [Alert plans (escalation policies)](https://upfour.io/docs/api/escalation-policies.md) | Who is told, in what order, after how long. | 8 endpoints |
| [On-call rotations](https://upfour.io/docs/api/oncall-schedules.md) | Rotations, overrides, and "who is on call right now". | 12 endpoints |
| [Playbooks (runbooks)](https://upfour.io/docs/api/runbooks.md) | The steps you take when something breaks, attached to monitors, with shared progress. | 7 endpoints |
| [Health advisor](https://upfour.io/docs/api/advisor.md) | Findings about your setup, such as monitors that alert nobody, and one call to apply a suggested fix. | 2 endpoints |

Pages & reporting

| [Status pages](https://upfour.io/docs/api/status-pages.md) | Public and client-facing uptime pages: structure, updates, subscribers, translations. | 53 endpoints |
| --- | --- | --- |
| [Status page update templates](https://upfour.io/docs/api/status-page-templates.md) | Saved wording for status page updates: title, status and message to reuse. | 4 endpoints |
| [Status page design templates](https://upfour.io/docs/api/status-page-design-templates.md) | Reusable status page designs: save the look of a page once and apply it to other pages. | 6 endpoints |
| [Reports](https://upfour.io/docs/api/reports.md) | Availability and SLA reporting: summaries, trends, exports, schedules, share links. | 21 endpoints |
| [SLA policies](https://upfour.io/docs/api/sla-policies.md) | Targets and business-hours masks that reports measure against. | 5 endpoints |

Organization

| [Organization](https://upfour.io/docs/api/organization.md) | Company-level settings. | 18 endpoints |
| --- | --- | --- |
| [Teams](https://upfour.io/docs/api/teams.md) | Teams and membership. | 14 endpoints |
| [Invites](https://upfour.io/docs/api/invites.md) | Invite colleagues — seats are unlimited everywhere. | 4 endpoints |
| [Clients (agency mode)](https://upfour.io/docs/api/clients.md) | The agency partition: clients, client teams, share links, archive/unarchive. | 13 endpoints |
| [Client templates](https://upfour.io/docs/api/client-templates.md) | Materialize monitors, pages and alert plans for a new client in one step. | 6 endpoints |

Platform

| [Token introspection](https://upfour.io/docs/api/me.md) | Who am I? What can this key do? The first call to make. | 1 endpoints |
| --- | --- | --- |
| [Webhook subscriptions](https://upfour.io/docs/api/webhook-subscriptions.md) | Outbound, signed webhooks — subscribe, test, inspect deliveries, redeliver. | 8 endpoints |