Pinglet Start free
Docs menu
Start here
Getting started
Core concepts
Publishing Message anatomy Subscribing & the app
Guides
Generic webhook Apprise Gatus GitHub Actions Heartbeats Home Assistant Komodo Soon Prometheus Alertmanager Proxmox VE Uptime Kuma
Reference
API reference Plans & errors

API reference

Base URL: https://pinglet.dev

Authenticated endpoints take Authorization: Bearer pinglet_<64 hex characters>, a namespace-scoped key minted in the dashboard. Endpoints marked none are anonymous: the unguessable topic key (or ping token) in the URL is the capability. See Plans & errors for status codes.

Publishing

Method Path Auth
POST /{ns}/{name} key
POST /v1/{ns}/{topic-key}/publish key

Both take the same JSON body (message anatomy) and return the same response (publishing). The name-addressed form creates the topic on first publish; the key-addressed form returns 404 for an unknown key. Add ?rewrite=alertmanager, ?rewrite=uptimekuma or ?rewrite=komodo to translate a third-party webhook payload.

Topics & history

Method Path Auth
POST /v1/{ns}/topics key
GET /v1/{ns}/{topic-key}/messages none

Create a topic: body {"prefix": "deploys"} (optional; 1–32 chars of a-z 0-9 - _). Returns {namespace, topic, key, name}. Every topic key is minted with a random unguessable suffix; you cannot bring a chosen key into existence. This endpoint always creates a push topic; heartbeat topics are created from the dashboard.

List messages: query parameters:

Param Meaning
limit Page size. Default 50, max 200.
since Message-id cursor: returns messages with id > since, oldest-first, for gap-free forward paging. Absent: latest messages, newest-first.

Public feeds

Method Path Auth
GET /{ns}/{topic-key} none
GET /{ns}/{name}/{topic-key} none
GET /{ns}/{topic-key}/events none

The first two render the topic’s browsable feed page (the share-link URL). /events is a server-sent-events stream of new messages.

Devices & subscriptions

Used by the mobile app; documented for completeness. All anonymous.

Method Path Purpose
POST /v1/devices Register a device: {"token": "<fcm-token>", "platform": "ios"|"android", "topics": [{"namespace": "acme", "topic": "<key>"}]}
GET /v1/devices/{id} The device and its subscriptions
DELETE /v1/devices/{id} Unregister the device
POST /v1/devices/{id}/subscriptions Subscribe: {"namespace": "acme", "topic": "<key>"}
DELETE /v1/devices/{id}/subscriptions/{ns}/{topic-key} Unsubscribe
PUT /v1/devices/{id}/mute Silence the device’s pushes until a point in time: {"until": "<RFC 3339>"} (max one year ahead)
DELETE /v1/devices/{id}/mute Unmute the device

Subscribing requires the topic to already exist.

While a device is muted no push is sent to it at all; messages are still stored, so the app catches up from history when it’s next opened. The mute expires on its own once until passes.

Check-ins (heartbeats)

Method Path Auth
GET /v1/ping/{token} none

Records a check-in against a heartbeat topic. Returns 200 ok, or 404 for an unknown token.

Key management

Method Path Auth
POST /v1/keys admin key
DELETE /v1/keys/{id} admin key

Minting and revoking keys over HTTP requires an admin-scoped key. For most accounts the dashboard is the way to manage keys: new keys are shown once, revocation takes effect immediately.

Health

Method Path Auth
GET /health none