API Reference

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

All requests require an Authorization: Bearer YOUR_API_KEY header.

Send a Notification

POST https://send.pushtower.com/:channel

Field	Type	Required	Description
`channel`	string	yes	Channel ID or alias (sent in the URL path)
`title`	string	yes	Notification title
`message`	string	yes	Notification body text
`imageUrl`	string	no	URL (`https`) of a rich image attachment shown in the notification
`senderName`	string	no	iOS only. Sender display name for communication-style notifications
`avatarUrl`	string	no	iOS only. URL (`https`) of a circular sender avatar. Setting this renders a communication-style notification
`sound`	string	no	Sound name (default: `default`)
`priority`	string	no	`low`, `normal`, or `high`
`data`	object	no	Custom payload data
`encrypted`	boolean	no	Enable E2E encryption

Communication Notifications (iOS)

Include an avatarUrl to render the notification in iOS’s messaging style — a circular sender avatar instead of the standard app-icon layout. This is the only way to show a custom per-notification image as a small icon; the app icon itself can’t be overridden.

avatarUrl — the circular avatar image (https, JPEG/PNG/GIF).
senderName — the bold name shown next to the avatar. Falls back to title if omitted.
title — used as the conversation name.

The avatar travels inside the encrypted payload for end-to-end-encrypted devices, so it works with encrypted: true too. On Android the fields are ignored and the notification renders normally.

curl -X POST https://send.pushtower.com/server-alerts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "title": "Production",
    "message": "Deploy finished",
    "senderName": "CI Bot",
    "avatarUrl": "https://example.com/ci-bot-avatar.png"
  }'

Example

curl -X POST https://send.pushtower.com/server-alerts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "title": "Deploy Complete",
    "message": "v2.4.1 is now live on production",
    "priority": "high"
  }'

Response

{
  "id": "ntf_abc123",
  "status": "delivered",
  "delivered_at": "2026-04-09T12:00:00Z"
}

Live Activities

POST /v1/live-activity

Start or update a Live Activity on the user’s lock screen. See Live Activities for details.

Channels

GET    /v1/channels          # List channels
POST   /v1/channels          # Create channel
GET    /v1/channels/:id      # Get channel
PATCH  /v1/channels/:id      # Update channel
DELETE /v1/channels/:id      # Delete channel

Devices

GET    /v1/devices            # List registered devices
DELETE /v1/devices/:id        # Remove a device

Rate Limits

All API endpoints are rate-limited to 100 requests per minute per API key. The response headers include:

X-RateLimit-Limit — Max requests per window
X-RateLimit-Remaining — Requests remaining
X-RateLimit-Reset — Unix timestamp when the window resets