API Reference

Base URL: https://api.pushtower.com

Authenticate with either:

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

The canonical OpenAPI contract is available at https://api.pushtower.com/openapi.json.

Preview

POST /api/notifications/preview validates and normalizes a notification without sending it. It returns presentation warnings and estimated recipients split by platform.

curl -X POST https://api.pushtower.com/api/notifications/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "server-alerts",
    "title": "Deploy complete",
    "message": "v2.4.1 is live",
    "preset": "deploy-success"
  }'

Send or schedule

POST /api/notifications uses the same body. Add scheduledAt to schedule delivery and idempotencyKey to make retries safe.

curl -X POST https://api.pushtower.com/api/notifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "server-alerts",
    "title": "Deploy complete",
    "message": "v2.4.1 is live",
    "preset": "deploy-success",
    "idempotencyKey": "deploy-v2.4.1"
  }'

Supported presets are deploy-started, deploy-success, deploy-failed, incident, warning, approval-needed, reminder, and progress.

Rich notifications additionally support imageUrl, sender, sound, badge, actions, data, and private.

Sender and avatar

sender sets who a notification is from. With an avatarUrl, iOS shows a communication notification with the circular avatar, and Android shows a conversation-style notification. An imageUrl can be sent alongside it.

{
  "channel": "code-review",
  "title": "Review requested",
  "message": "Alice asked you to review #482",
  "sender": {
    "name": "Alice",
    "avatarUrl": "https://example.com/alice.png"
  }
}

A channel can have a default sender that applies when a notification sets none. Set it with PATCH /api/channels/:id and {"sender": {"name": "…", "avatarUrl": "…"}}, or remove it with {"sender": null}. A notification’s own sender replaces the default entirely; the two are never combined.

The earlier flat fields senderName and avatarUrl are still accepted but deprecated. A request may use either sender or the flat fields, not both. On the GET shorthand, use the senderName and avatarUrl query parameters.

Shorthand send

Simple integrations may call POST https://send.pushtower.com/:channel with title and message. Use the canonical API when preview, scheduling, or idempotency is required.

Channels

GET    /api/channels
POST   /api/channels
PUT    /api/channels/ensure/:alias
GET    /api/channels/:id
PATCH  /api/channels/:id
DELETE /api/channels/:id