API reference

Endpoints for your server: send a notification, read its status back, and poll decision answers. They use a project API key.

Authentication

Send the key as Authorization: Bearer $PINGLOOM_API_KEY. Sending needs the notifications:send scope; reading status needs events:read. Keys start with pl_live_ in production and pl_test_ everywhere else.

Headers

• Content-Type: application/json is required. Anything else returns 415.
• Idempotency-Key is optional: 1 to 255 printable ASCII characters. The same key with the same body returns the original event for 24 hours, with the response header Idempotent-Replayed: true. The same key with a different body returns 409.
• The 202 response carries Location, the URL to read the status from.

Fields

POST /v1/notifications takes a JSON object. Only title is required.

The whole request body is at most 32768 bytes. Any other key returns 422 UNKNOWN_FIELD.

Response

PingLoom answers 202 only after the event is stored. Delivery to devices happens afterwards.

HTTP/1.1 202 Accepted
Location: /v1/notifications/01J9ZQ8M3K7W4X2B6N5T0R1VCD

{
  "event_id": "01J9ZQ8M3K7W4X2B6N5T0R1VCD",
  "status": "accepted",
  "created_at": "2026-10-22T09:30:00Z",
  "status_url": "/v1/notifications/01J9ZQ8M3K7W4X2B6N5T0R1VCD",
  "idempotent_replay": false,
  "deduplicated": false
}

idempotent_replay is true when the response repeats an earlier request. deduplicated is true when an existing event with the same external_id was returned because the project's deduplication window is on.

Errors

Every error uses one envelope. request_id is what support needs. Validation errors list each problem in details[].

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request has invalid fields.",
    "request_id": "req_01J9ZQ8M3K",
    "details": [
      { "field": "title", "message": "Title is required.", "code": "REQUIRED" }
    ]
  }
}

Validation detail codes

Status endpoint

GET /v1/notifications/{event_id} returns the event's status and a delivery summary. It needs the events:read scope and only sees events from the key's own project. An unknown id, or one from another project, returns 404. See Status codes for the words.

Decision cards

Add a decision object to POST /v1/notifications to ask your team a question. Owners and admins answer from the app or dashboard; PingLoom records the answer and never acts on it. Read the answer back in either of two ways, both with the events:read scope:

• GET /v1/notifications/{event_id} includes a decision block: status (pending, decided, expired or cancelled), option_id, label, comment, decided_by (user_id and name), decided_at and via.
• GET /v1/decisions?status=&since=&limit= lists your project's decisions, oldest change first, with the same block plus event_id, external_id, channel and your data. limit is 1 to 100 (default 50). The response has next_cursor and has_more. Send next_cursor back as since; the cursor is opaque, and an empty page returns the cursor you sent. A decision appears again, in its new state, after it is decided or expires.

Limits: 2 to 5 options, option id a slug up to 32 characters, label up to 40, prompt up to 200, comment up to 500, expires_in from 5 minutes to 7 days (default 24 hours). A decision raises priority low to normal. The push never carries the prompt or options. Over the plan's monthly decision limit returns 429 QUOTA_EXCEEDED; decision.policy names a decision policy (slug or id) that an owner or admin created in the dashboard (Business plan). It sets who may decide and how many different people must approve; you can name one but never define one (decision.roles returns 422). Add decision.requested_by so a policy can stop that person approving their own request. The decision then carries policy, outcome and votes. Signed-in users answer with POST /v1/events/{event_id}/decision (409 DECISION_CLOSED once someone has answered).

Downloads