API Reference

Authentication

Every /v2/* endpoint except the public invite/webhook/status routes and /health requires authentication. Three credential types are accepted; the auth middleware tries them in a fixed order.

API keys (integrations)

API keys belong to integrations and are the primary credential for monitoring tools and scripts. Four header forms are accepted, checked in this order:

# 1. Dedicated header (checked first)
X-OpsPing-Key: YOUR_API_KEY

# 2. Primary Authorization scheme
Authorization: OpsPingKey YOUR_API_KEY

# 3. OpsGenie-compatible scheme (drop-in migration)
Authorization: GenieKey YOUR_API_KEY

# 4. Legacy: raw key as a Bearer token
Authorization: Bearer YOUR_API_KEY

• Keys are looked up by SHA-256 of the raw key and verified with bcrypt (v2 keys). A 15-second in-memory cache avoids re-hashing on every request — revoked or rotated keys stay valid for up to ~15 seconds.
• A key carries scopes: read, write, delete, config. Method mapping: GET/HEAD/OPTIONS → read, POST/PUT/PATCH → write, DELETE → delete. Keys minted via the API get read/write/delete but not config (the integrations router requires config, so integration keys cannot manage integrations).
• A key can be bound to a team; team-bound keys only see and mutate their team's resources plus global (team-less) ones.
• Internally a key authenticates as a synthetic user { sub: integrationId, role: "api_key", teamId }. Endpoints documented as "JWT only" reject this context.
• Browser note: CORS allowHeaders is Content-Type, Authorization only. Cross-origin browser callers must use an Authorization scheme — X-OpsPing-Key fails preflight. Server-to-server callers are unaffected.

JWT (user sessions)

Authorization: Bearer <access-token>

Issued by POST /v2/auth/login. Access tokens are HS256 JWTs with a 15-minute default expiry (JWT_EXPIRY); refresh tokens last 30 days. Each token carries a jti (revocable via logout) and a tokenVersion — incrementing a user's tokenVersion (password reset, block, role/permission change, revoke-all) invalidates all outstanding tokens. Blocked accounts get 403 Account is blocked.

httpOnly cookie (dashboards)

Login also sets Set-Cookie: token=<jwt>; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=900. The admin SPA authenticates with this cookie alone. Cookie auth is only attempted when no Authorization header is present — a malformed Authorization header yields 401 even with a valid cookie. The cookie is Secure, so browsers drop it over plain HTTP (except localhost).

Authorization model

Rate limits

Conventions

Base URL

https://api.ops-ping.com        # hosted
https://<your-host>            # private deployment

Response envelope

Most successful responses use one of three shapes:

// Single resource — respond()
{ "data": { … }, "took": 0.012, "requestId": "uuid" }

// List — respondList()
{ "data": [ … ], "totalCount": 42, "took": 0.012, "requestId": "uuid",
  "nextCursor": "…" }            // only when a cursor exists

// 202 Accepted — respondAccepted() (alert mutations)
{ "result": "Request will be processed", "took": 0, "requestId": "uuid" }

took is wall-clock seconds for the request (3 decimals); requestId is a fresh UUID per response (not correlated to any request header).

Errors

// Structured error (respondError)
{ "message": "Invalid pagination cursor", "code": "PAGINATION_CURSOR_INVALID", "took": 0, "requestId": "uuid" }

// Validation failure (zod)
{ "message": "Invalid request: message: String must contain at least 1 character(s); …", "code": "BAD_REQUEST", … }

// Common codes: UNAUTHORIZED (401), FORBIDDEN (403), BAD_REQUEST / VALIDATION (400),
// NOT_FOUND (404), RATE_LIMIT_EXCEEDED (429), PAGINATION_CURSOR_INVALID (400)

Pagination

List endpoints accept ?limit= (default 50, max 200 on most; alerts: default 20, max 100) and ?cursor= (base64url-encoded DynamoDB key, returned as nextCursor). An undecodable cursor → 400 PAGINATION_CURSOR_INVALID.

Identifiers

Resources use UUID ids. Alerts additionally have a numeric tinyId and most alert routes accept either as :identifier. tinyId is a random number 0–99999 with no uniqueness check — always address alerts by UUID.

Timestamps & bodies

All timestamps are UTC ISO-8601 strings. Request bodies are JSON, max 1 MB. Several routers validate bodies with zod schemas (noted per endpoint); others accept unvalidated JSON — send only documented fields. All dates in responses are strings; null means unset.

OpsGenie envelope

Alert create/mutate responses follow the OpsGenie convention of 202 Accepted + requestId. OpsPing processes alert creation synchronously (dedup, escalation, and notification dispatch run immediately, dispatch fire-and-forget) — but, like OpsGenie, the create response does not include the alert ID. Look the alert up by alias via the list endpoint.

Alerts

The core resource. Alert objects look like this (JSON-stored fields are parsed back to objects in responses):

{
  "id": "uuid", "tinyId": 12345, "alias": "cpu-prod-web-3",
  "message": "CPU usage > 90% on prod-web-3",
  "status": "open",              // open | acknowledged | closed
  "acknowledged": false, "isSeen": false,
  "readBy": [{ "userId": "…", "userName": "…", "readAt": "…" }],
  "tags": ["cpu"], "visibleTo": null,
  "snoozed": false, "snoozedUntil": null,
  "count": 1,                    // dedup hit counter
  "lastOccurredAt": "…", "createdAt": "…", "updatedAt": "…",
  "source": "Datadog", "owner": null, "priority": "P2",
  "responders": [{ "id": "…", "type": "schedule", "name": "Primary On-Call" }],
  "entity": "", "description": "", "details": {}, "actions": []
}

curl -X POST https://api.ops-ping.com/v2/alerts \
  -H "Authorization: OpsPingKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "CPU usage > 90% on prod-web-3",
    "alias": "cpu-prod-web-3",
    "priority": "P2",
    "source": "Datadog",
    "tags": ["cpu", "production"],
    "details": { "cpu_pct": "94.2", "host": "prod-web-3" },
    "responders": [{ "type": "schedule", "name": "Primary On-Call" }]
  }'

curl "https://api.ops-ping.com/v2/alerts?status=open&limit=50" \
  -H "Authorization: OpsPingKey YOUR_API_KEY"

Lifecycle actions

All lifecycle mutations return 202 {"result":"Request will be processed",…} (after the work is already done), write an activity entry, and drive the escalation engine in the background. All enforce team access.

Notes, activities, details, responders, tags

Attachments

Presigned-S3 file attachments per alert (two-step upload: mint → PUT → complete). Limits: 10 MB max file size, 10 attachments per alert; pending mints older than 15 minutes never consumed the upload URL and don't count against the quota. All four endpoints team-checked, and all return 503 ATTACHMENTS_DISABLED when the deployment has no attachments bucket configured.

curl -X POST https://api.ops-ping.com/v2/alerts/ALERT_ID/attachments \
  -H "Authorization: OpsPingKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"heap-dump.png","contentType":"image/png","size":482133}'
# → uploadUrl … then:
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @heap-dump.png
curl -X POST https://api.ops-ping.com/v2/alerts/ALERT_ID/attachments/ATTACHMENT_ID/complete \
  -H "Authorization: OpsPingKey YOUR_API_KEY"

User Auth & MFA

User session endpoints under /v2/auth. None accept API-key auth as the subject (it is user auth), and all success responses use the standard envelope.

curl -X POST https://api.ops-ping.com/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"oncall@example.com","password":"…"}'

MFA (TOTP)

SSO (OIDC)

Users, Teams & Invites

Users — /v2/users

curl "https://api.ops-ping.com/v2/users?q=alice" \
  -H "Authorization: OpsPingKey YOUR_API_KEY"

Teams — /v2/teams

Team roles — /v2/teams/:teamId/roles

Custom per-team role definitions: {id, name, teamId, permissions: Record<string,boolean>, createdAt}. Routes: GET /, POST / (201), GET|PATCH|DELETE /:roleId. Team-checked — but against the role's stored team, so the path :teamId is decorative on the single-role routes. Note: this router has no scope/permission middleware — any authenticated caller (even a read-scoped API key) can write roles for their team.

Invites — /v2/invites

Schedules & PTO

Schedules — /v2/schedules

curl -X POST https://api.ops-ping.com/v2/schedules \
  -H "Authorization: OpsPingKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary On-Call",
    "timezone": "America/New_York",
    "rotations": [{
      "name": "Weekly",
      "type": "weekly",
      "startDate": "2026-08-03T00:00:00Z",
      "participants": [{ "type": "user", "name": "alice" }, { "type": "user", "name": "bob" }]
    }]
  }'

Rotations & overrides

On-call queries

curl "https://api.ops-ping.com/v2/schedules/SCHEDULE_ID/on-calls" \
  -H "Authorization: OpsPingKey YOUR_API_KEY"

PTO requests — /v2/pto-requests

Escalations

Escalation policies: ordered rules that notify a schedule/user/team after a delay while an alert stays un-acked. Validated by local zod schemas (400 VALIDATION on failure). Regular JWT users default to read-only (escalations is not a user-scoped resource); writes need an explicit grant.

curl -X POST https://api.ops-ping.com/v2/escalations \
  -H "Authorization: OpsPingKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Escalation",
    "rules": [
      { "delayMinutes": 0,  "recipientType": "schedule", "recipientId": "SCHEDULE_ID" },
      { "delayMinutes": 15, "recipientType": "user",     "recipientId": "USER_ID", "notifyType": "all" }
    ]
  }'

Incidents

Declared incidents (OpsPing-native; not part of the OpsGenie compat surface). Regular JWT users have default write.

Postmortems

Incident write-ups: {id,incidentId,summary,rootCause,timeline:[{time,description}],actionItems:[{description,assignee?,status:pending|in_progress|done}],createdAt,updatedAt}. Access is scoped through the parent incident (team + tenant checked against the incident; if the incident was deleted, the tenant check falls back to the postmortem's own tenant). Gated under the incidents permission — regular users have default write.

curl -X POST https://api.ops-ping.com/v2/postmortems/generate \
  -H "Authorization: OpsPingKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"incidentId":"INCIDENT_ID"}'

Services

Service catalog entries: {id,name,description,status,teamId,visibility,tags,createdAt,updatedAt} (status default ok, visibility default internal). Regular JWT users are read-only by default (services is not user-scoped); writes need an explicit grant or admin. Standard CRUD: GET /, POST /, GET /:id, PATCH /:id, DELETE /:id.

Heartbeats

Dead-man's-switch monitoring: your job pings OpsPing; if a ping isn't received within the configured interval, OpsPing opens an alert. name is the primary key.

curl -X POST https://api.ops-ping.com/v2/heartbeats/nightly-backup/ping \
  -H "Authorization: OpsPingKey YOUR_API_KEY"

Maintenance Windows

Time windows during which the heartbeat-expiry job suppresses alert creation. A window applies when enabled and startTime ≤ now ≤ endTime, and is global when both teamId and serviceId are null, otherwise scoped to that team/service. Regular JWT users default to read-only.

Channels

Per-user SMS / voice / email delivery targets used by notification rules. Channel object: {id,userId,type,value,label?,verified,lastTestAt?,lastTestResult?,createdAt,updatedAt}. This router answers with raw {"ok":true,…} shapes — no took/requestId envelope. Admins can operate on another user's channels with ?userId=.

curl -X POST https://api.ops-ping.com/v2/channels \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"type":"sms","value":"+15551234567","label":"Personal cell"}'

Notification Rules

Per-user rules that route matching alerts to channels, with optional delay and repeat. Rule object: {id,userId,name,enabled,criteria,action,repeat,order,createdAt,updatedAt}. Dispatch runs on alert create (not dedup); delayed/repeat deliveries are durable and re-check the alert at fire time. Every dispatch outcome is written to the audit log (?entityType=notification-rule).

curl -X POST https://api.ops-ping.com/v2/notification-rules \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Page me on P1",
    "criteria": { "priorities": ["P1"] },
    "action":  { "channelIds": ["CHANNEL_ID"], "delayMins": 0 },
    "repeat":  { "enabled": true, "intervalSec": 300 }
  }'

Alert Policies

Server-side preprocessing applied to every alert on create — including alerts created via inbound webhooks and email (the exact create path is shared). Policies are ordered, first-match: the first enabled policy whose match block fits the incoming alert wins; evaluation stops there. Match fields are AND-ed; an empty match matches every alert. Scope: policies are per-tenant; a policy may bind to a teamId (null = tenant-global), and the single-resource routes are team-checked — the list is tenant-wide, not team-filtered. Every mutation writes an audit entry (alert_policy.create|update|delete|reorder; the dry-run writes nothing). Not supported yet: time-based conditions and payload enrichment. Gated under the escalations permission — regular JWT users default to read-only.

curl -X POST https://api.ops-ping.com/v2/alert-policies \
  -H "Authorization: OpsPingKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Silence synthetic checks at night",
    "match": { "sources": ["synthetics"], "priorities": ["P4","P5"] },
    "actions": { "suppress": true }
  }'

curl -X POST https://api.ops-ping.com/v2/alert-policies/dry-run \
  -H "Authorization: OpsPingKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alert":{"source":"grafana","priority":"P2","message":"High error rate"}}'
# → {"data":{"matched":{"id":"…","name":"Downgrade grafana noise","order":2},
#            "outcome":"continue","mutations":{"setPriority":"P3","addTags":["auto-downgraded"]}}}

Status Pages

One hosted status page per tenant, plus public subscriber management. Admin config lives under /v2/status-page and requires an admin JWT or an API key with the config scope; the public surface under /v2/public/status-page/:slug is unauthenticated (gated per page, rate-limited per IP). Incidents become status-page content via their statusPageEntry field — see Incidents (PATCH /v2/incidents/:id).

Public status page

Three-mode gate, checked per request: public — open; link — requires the access key in the X-Status-Key header (a wrong/missing key is 404, never 401/403, so the endpoint never confirms a gated slug exists); login — requires an authenticated session (401 {"message":"authentication required"} when unauthenticated; a valid user from another tenant gets 404). Unknown slugs are 404 {"message":"not found"}.

curl "https://api.ops-ping.com/v2/public/status-page/acme" 
# link mode:
curl -H "X-Status-Key: THE_ACCESS_KEY" "https://api.ops-ping.com/v2/public/status-page/acme"

Inbound Webhooks & Email

Unauthenticated intake endpoints where the URL token is the credential (SHA-256 hashed, timing-safe compared; 401 for an unknown integration or bad token alike, 403 FORBIDDEN when the integration is disabled, 429 past 300 req/min per token). Created alerts inherit the integration's team/tenant and run the identical POST /v2/alerts pipeline — dedup, routing rules, alert policies, escalation, push. Webhook URLs and inbound email addresses are minted and rotated on the integrations endpoints.

curl -X POST https://api.ops-ping.com/v2/webhooks/inbound/INTEGRATION_ID/WEBHOOK_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"message":"Disk full on db-1","alias":"disk-db-1","priority":"P2"}'

Integrations & Tokens

Integrations own API keys and inbound webhook URLs. This router additionally requires the config scope for API-key callers on every method — and keys minted here never get config — so in practice integration management is JWT-only. Regular JWT users default to read; writes need an explicit grant.

curl -X POST https://api.ops-ping.com/v2/integrations/INTEGRATION_ID/regenerate-key \
  -H "Authorization: Bearer YOUR_ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

Tokens — /v2/tokens

Cross-integration view of all API keys. GET /v2/tokens → {"data":[{id,integrationId,integrationName,keyPrefix,scopes,createdAt,lastUsedAt}]} (newest first, no pagination). DELETE /v2/tokens/:id revokes a key (:id is the key record ID — the SHA-256 hex of the raw key; API-key callers need the delete scope). Revocation takes effect within ~15 seconds.

Saved Searches

Named alert-list queries: {id,name,query,teamId,createdAt}. Standard CRUD: GET / (query: limit, cursor, q substring over name+query), POST / ({"name","query"}), PATCH /:id, DELETE /:id.

Audit Log

curl "https://api.ops-ping.com/v2/audit-log?entityType=notification-rule&from=2026-07-01&limit=100" \
  -H "Authorization: OpsPingKey YOUR_API_KEY"

Reports

Alert analytics computed on demand over a trailing window. Team-scoped: callers with a teamId see only their team's alerts (callers without one — including teamless admins — see all); team-less alerts are invisible to team-bound callers. No ?allTeams= override. All stats endpoints accept ?days= (default 30, clamped 1–365) and scan the full window — cost grows with days.

curl "https://api.ops-ping.com/v2/reports/summary?days=7" \
  -H "Authorization: OpsPingKey YOUR_API_KEY"

On-call hours — /v2/reports/on-call-hours

curl "https://api.ops-ping.com/v2/reports/on-call-hours?from=2026-08-01T00:00:00Z&to=2026-08-31T00:00:00Z&format=csv" \
  -H "Authorization: OpsPingKey YOUR_API_KEY"

Report schedules — /v2/reports/schedules

Additional APIs

Push tokens — /v2/push-tokens

Inbound webhooks — /v2/webhooks/inbound/:integrationId/:token

Public alert intake authenticated by the per-integration URL token, with auto-detection for Alertmanager, Grafana, CloudWatch/SNS, and Datadog payloads — see Inbound Webhooks & Email.

Alert policies — /v2/alert-policies

Server-side alert preprocessing on create (suppress, delay, auto-ack/close, add tags, set priority) — full CRUD, dry-run, and reorder documented under Alert Policies.

Routing rules — /v2/routing-rules

Assign a team to incoming alerts that match: {id,name,enabled,order,match:{priorities?,sources?,tags?,entities?,messageRegex?},targetTeamId,createdAt,updatedAt} (empty match = catch-all). CRUD: GET / (team-scoped list), POST / (201), PUT|DELETE /:id. Manage rights: global admins, or admin/lead members of the target team; retargeting requires rights on both teams. Note: PUT is a partial merge, not a full replace.

Forwarding rules — /v2/forwarding-rules

User-scoped notification forwarding (GET /, POST /, GET /:id, PUT /:id, DELETE /:id). JWT only — API keys get 403 Forwarding rules are user-scoped. Fields: {id,fromUserId,toUserId,startDate?,endDate?,alias?,enabled,createdAt}. No input validation (missing toUserId is stored as-is); PUT responses leak internal storage keys (PK/SK).

Postmortems — /v2/postmortems

Incident write-ups — CRUD, audit-trail generation, and Markdown/PDF export documented under Postmortems.

Public status — /v2/public/status

Unauthenticated, unrate-limited. Incidents flagged for the status page: {"data":[{id,message,severity,status,createdAt,resolvedAt,updatedAt}],"generatedAt":"…","overallStatus":"operational"|"degraded"}. An incident appears when its statusPageEntry.enabled is true; severity comes from the status-page entry (default info), not the incident priority.

Data export — /v2/export

GET /v2/export — GDPR-style self-export for the calling user: {"data":{"exportedAt","user":{…}|null,"alerts":[… assigned to you …],"notificationRules":[…],"channels":[…]}} (pseudo-envelope: no took/requestId; no rate limiting). Results are a single database page — very large datasets are silently truncated.

Account — /v2/account

GET /v2/account — deployment info: {"data":{"name":"OpsPing","userCount":n,"teamCount":n,"plan":"self-hosted"}}. Counts are global (not team-scoped) and visible to any authenticated caller including API keys.

Health & Debug

curl https://api.ops-ping.com/health
curl "https://api.ops-ping.com/health?deep=1"

OpsGenie Compatibility

The alert pipeline is drop-in compatible with the OpsGenie v2 REST API: point your existing integration at the OpsPing base URL and keep your GenieKey header — it is accepted as-is. See the migration guide for step-by-step instructions and the import script.