HTTP API reference
Base URL: http://lantern.dply.io
· All publish and subscription routes are under /api/v1
Publish a message
POST JSON or plain text. Prefer the scoped URL so topic slugs stay unique per project.
Scoped (recommended)
POST http://lantern.dply.io/api/v1/o/{organization_slug}/{project_slug}/p/{topic_slug}Legacy
Only safe when your topic slug is globally unique. Otherwise you receive 409 ambiguous_topic_slug.
POST http://lantern.dply.io/api/v1/p/{topic_slug}Authentication
- Public topics: no topic secret required.
- Secret topics: send the topic key as Authorization: Bearer …, X-Pingline-Key, or ?auth=
- If the organization has an org publish token configured, also send header X-Pingline-Organization-Key (see Billing).
JSON body
Content-Type: application/json. Message text can be in message or body.
{
"title": "Deploy finished",
"message": "v1.2.3 is live",
"priority": 3,
"tags": ["prod", "api"],
"meta": { "commit": "abc123" }
}- title — optional string
- message or body — notification body (required non-empty)
- priority — optional integer 1–5 (default 3)
- tags — optional string array
- meta — optional object
Non-JSON body
Raw request body becomes the notification message. Optional title via X-Title or Title header; priority via X-Priority or Priority (1–5); tags via X-Tags or Tags (comma-separated).
Success
201 Created
{
"id": 42,
"topic": "alerts",
"time": "2026-03-22T12:00:00+00:00"
}Register a push subscription
Same auth rules as publish (public vs secret topics). Rate limited.
Scoped
POST http://lantern.dply.io/api/v1/o/{organization_slug}/{project_slug}/topics/{topic_slug}/subscriptionsLegacy
POST http://lantern.dply.io/api/v1/topics/{topic_slug}/subscriptionsWeb Push body
{
"driver": "webpush",
"subscription": {
"endpoint": "https://…",
"keys": { "p256dh": "…", "auth": "…" }
}
}FCM / APNs
driver: fcm or apns with token set to the device token string.
Success
201 Created — { "ok": true }
VAPID public key
GET http://lantern.dply.io/api/v1/push/vapid-public-keyReturns JSON publicKey and configured boolean for browser subscription.
Common errors
| HTTP | error | Meaning |
|---|---|---|
| 400 | empty_message | Body was empty after parsing |
| 401 | unauthorized | Missing or wrong topic key / subscribe auth |
| 401 | organization_key_required | Org token enabled; send X-Pingline-Organization-Key |
| 403 | forbidden | Client IP is blocked for publish |
| 403 | subscription_limit_reached | Topic hit max_push_subscriptions_per_topic |
| 404 | topic_not_found | Unknown slug or wrong org/project |
| 409 | ambiguous_topic_slug | Legacy path; use scoped publish URL |
| 429 | publish_limit_exceeded | Daily organization cap; JSON includes limit, window, used |
Throttle limits apply per route (see Laravel throttle middleware).