REST API

The PathWatch REST API is the same API the web app uses — there are no internal-only endpoints. Anything you can do in the app, you can do programmatically.

Base URL

https://api.pathwatch.app/api/v1

Authentication

Two methods:

API keys — the method for programmatic access. Create one at Settings → API keys (format pw_live_..., shown once) and send it as a bearer token:

Authorization: Bearer pw_live_xxxxxxxxxxxxxxxx

Each API key is bound to one organisation and carries scopes that cap what it can touch:

Scope	Grants
`org:admin`	All scopes below
`monitors:read` / `monitors:write`	Monitors, check results, groups, maintenance windows
`alerts:read` / `alerts:write`	Alert channels, rules, history, escalation policies
`status_pages:read` / `status_pages:write`	Status pages and themes
`runners:read` / `runners:write`	Self-hosted runners
`incidents:read` / `incidents:write`	Incidents

A key can never grant more than its creator’s own role permits.

Session cookies — used by the web app after sign-in. Not intended for programmatic access; use an API key instead. Session-authenticated users who belong to multiple organisations can target a specific one by sending an X-Org-Id header (membership is verified); otherwise requests run against the default organisation.

Versioning

All endpoints are under /api/v1/. Breaking changes go in /api/v2/ with at least 6 months overlap. Non-breaking additions ship under v1.

Pagination

Collection endpoints use page-based pagination:

Query param	Default	Range
`page`	`1`	≥ 1
`limit`	`20`	1–100

Requests with limit above 100 are rejected with a validation error — page through instead. Paginated responses share one envelope:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 57,
    "totalPages": 3,
    "hasMore": true
  }
}

Errors

All errors return a consistent JSON body:

{
  "error": "Monitor 'mon_123' not found",
  "code": "NOT_FOUND",
  "details": { }
}

error is a human-readable message, code is a stable machine-readable identifier, and details is included only when there is structured context (e.g. validation issues, the missing entitlement, or retry timing).

HTTP status	`code`	When
400	`VALIDATION_ERROR`	Request body or query params failed validation (`details` lists the issues)
403	`PERMISSION_DENIED`	Your role or API-key scope doesn’t allow the action
403	`ENTITLEMENT_REQUIRED`	The feature isn’t included in your plan (`details.entitlement` names it)
404	`NOT_FOUND`	Resource doesn’t exist or belongs to another organisation
409	`CONFLICT`	The request conflicts with current state (e.g. duplicate slug)
429	`RATE_LIMIT_EXCEEDED`	Too many requests (`details.retryAfterSeconds` says how long to wait)
500	`INTERNAL_ERROR`	Something broke on our side — safe to retry with backoff

Rate limits

Every /api/v1/* request counts against a fixed one-minute window:

Context	Limit
Authenticated (per organisation)	300 requests/min
Unauthenticated (per IP)	10 requests/min

Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). Going over returns 429 with the error body above.

Sign-in, sign-up and password-reset endpoints have separate, much tighter per-IP limits to block brute-force attempts.

Resource catalogue

Everything below lives under the base URL. Endpoints follow standard REST conventions (GET list/read, POST create, PATCH update, DELETE remove); the OpenAPI spec documents every route, parameter and response shape.

Monitoring

Resource	Path	Purpose
Monitors	`/monitors`	Create, configure, pause/resume (single and bulk), run-now and delete monitors of every check type
Check results	`/monitors/:id/checks`	Raw per-check results with filters, single-result detail, and CSV/JSON export (`/checks/export`)
Uptime & aggregates	`/monitors/:id/uptime`, `/monitors/:id/aggregates`	Uptime percentages and summarised history for charts and SLA reporting
Monitor groups	`/monitor-groups`	Tag-style grouping used by dashboards and alert-rule scoping
Maintenance windows	`/maintenance-windows`	Scheduled (optionally recurring) windows that suppress alerts and/or pause monitors
Locations	`/locations`	The user-facing city list your plan can check from
Regions	`/regions`	The cloud regions backing those locations, with health state
Flow step palette	`/plugins/flow/components`	Metadata for every browser-flow step type (used to build flow editors)

Alerting

Resource	Path	Purpose
Alert channels	`/alert-channels`	Notification destinations (email, Slack, webhook, PagerDuty, …) incl. test-send
Alert rules	`/alert-rules`	Conditions that fire alerts, their scope, confirmation settings and channel bindings; active-alert list and acknowledge
Alert history	`/alerts/history`	Every notification sent: rule, channel, monitor and delivery outcome
Alert capabilities	`/alert-capabilities`	Which channel types and alerting features your plan includes
Escalation policies	`/escalation-policies`	Multi-step escalation chains with per-step delays
Notifications	`/notifications`	In-app notification feed (list, mark read)

Status pages & incidents

Resource	Path	Purpose
Status pages	`/status-pages`	Pages, sections, components, access control, custom domains and subscribers
Themes	`/themes`	Built-in and custom status-page themes
Incidents	`/incidents`	Incident lifecycle: create, update, post updates, resolve

Infrastructure

Resource	Path	Purpose
Runners	`/runners`	Register and manage self-hosted runners (returns the one-time `rt_` token on create)

Organisation & account

Resource	Path	Purpose
Organisations	`/orgs`, `/org`	List your orgs; manage the active org’s settings and members
Roles	`/org/roles`	System and custom roles with their permission matrix
Security policy	`/org/security-policy`	Org-wide requirements such as mandatory 2FA
Invitations	`/org/invitations`, `/invitations`	Send and accept membership invitations
User	`/user`	Your profile, sessions, data export and account deletion
API keys	`/api-keys`	Create, list and revoke API keys
Audit log	`/audit-log`	Who changed what, when (admin read)
Entitlements	`/entitlements`	Plans, your active entitlements and slot usage
Billing	`/billing`	Subscription state, checkout and invoices (Paddle-backed)
Retention	`/retention`	Your org’s effective data retention window

Real-time events

GET /events is a Server-Sent Events (SSE) stream the web app uses for live updates (check results, status changes). Connect with an Accept: text/event-stream request to consume the same stream.

Public endpoints

A few endpoints are deliberately unauthenticated:

GET|POST /heartbeat/:token — heartbeat monitor ping endpoint; the token is the credential.
Public status-page views and uptime badges — readable by anyone you share the URL with (subject to the page’s access mode).
/unsubscribe — one-click unsubscribe links in notification emails; the signed token in the URL is the proof of identity.

OpenAPI spec

The full machine-readable spec (OpenAPI 3.1) is published at:

https://api.pathwatch.app/openapi.json
https://api.pathwatch.app/api/v1/openapi.json

Both URLs serve the same document. Import it into Swagger UI, Postman, Insomnia or Hoppscotch for an interactive explorer, or generate typed clients with openapi-typescript, openapi-generator, or any other OpenAPI tool — the PathWatch web app itself is built from a client generated from this spec.