API reference
Base URL: https://app.pinglet.co.uk
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.
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 |
Subscribing requires the topic to already exist.
Check-ins (dead man’s switch)
| Method | Path | Auth |
|---|---|---|
GET |
/v1/ping/{token} |
none |
Records a dead man’s switch check-in. 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 |