Personal access tokens & API

How to create tokens, common endpoints, idempotency, rate limits.

Creating a token

Settings → API tokens → Generate token. Pick a name and a scope (currently single-scope: full org-level read/write). Pulse shows the token once; copy it then.

Using a token

curl -fsS https://pulse.example.com/api/v1/monitors \
    -H "Authorization: Bearer pat_..."

Tokens carry the issuing user’s permissions in their active org. Revoke from the same page.

Common endpoints

GET    /api/v1/healthz
GET    /api/v1/monitors
POST   /api/v1/monitors
GET    /api/v1/monitors/:id
PATCH  /api/v1/monitors/:id
DELETE /api/v1/monitors/:id

GET    /api/v1/incidents
POST   /api/v1/incidents              # manual declare
POST   /api/v1/incidents/:id/ack
POST   /api/v1/incidents/:id/resolve

GET    /api/v1/alerts/rules
POST   /api/v1/alerts/rules

GET    /api/v1/status-pages
POST   /api/v1/status-pages
POST   /api/v1/status-pages/:id/incidents       # link / publish
DELETE /api/v1/status-pages/:id/incidents/:incid

GET    /api/v1/overview                # dashboard payload
GET    /api/v1/metrics                  # Prometheus exposition

GET    /api/v1/public/:slug             # public status JSON bundle
GET    /status/:slug                    # public status HTML (no auth)
GET    /status/:slug/rss.xml            # RSS feed (no auth)

Idempotency

State-changing endpoints accept Idempotency-Key (any string up to 128 chars). Pulse caches the response keyed by (key, org, method, path) for 24 hours; replays return the original response. Use for retries during incidents.

Rate limits

Unauthenticated: 30 req/min/IP.
Authenticated: 300 req/min/user.
Heartbeat endpoint: per-token, unmetered (it’s the whole point).

Exceeds return 429 Too Many Requests with Retry-After.