API Reference
The PushWard API is a REST API for managing iOS Live Activities via Apple Push Notification service (APNs).
Base URL
https://api.pushward.appAuthentication
All endpoints (except /health) require a Bearer token in the Authorization header:
Authorization: Bearer hlk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345Tokens use the hlk_ prefix (integration keys). Create them in the iOS app's settings screen and copy the value once — only the SHA-256 hash is stored server-side, so tokens cannot be recovered if lost. See Authentication for scopes and slug-restriction rules.
Activity State Machine
Activities follow a state machine with two client-visible states:
| State | Description |
|---|---|
ended | Inactive (default on creation) |
ongoing | Active Live Activity running on device |
State Transitions
Transitions are triggered via PATCH /activities/{slug}:
| From | To | Push Action |
|---|---|---|
ended | ongoing | Push-to-start (starts Live Activity) |
ongoing | ongoing | Push update (updates content) |
ongoing | ended | Push end (dismisses after 4 hours) |
Activities may also enter an internal preempted state when the server evicts the lowest-priority activity to stay under the ongoing limit. Clients cannot set preempted directly — patch the activity back to ongoing to restart it.
Priority and Eviction
Each activity has a priority (0-10, default 0). When the ongoing activity limit (default 5) is exceeded, the server evicts the lowest-priority, oldest activity. Evicted activities transition to preempted and can be restarted.
Rate Limiting
All API endpoints are rate-limited per IP address:
| Endpoint | Limit |
|---|---|
Auth endpoints (POST /auth/*) | 10 requests per minute |
| All other endpoints | 200 requests per minute |
Exceeding the rate limit returns HTTP 429 Too Many Requests with an application/problem+json body (code: "rate_limit.exceeded") plus a Retry-After response header and a retry_after_ms extension. Back off accordingly. See Errors for the full Problem Details shape.
Endpoints
| Section | Description |
|---|---|
| Authentication | Token management and user profile |
| Activities | Create, list, update, and delete activities |
| Notifications | Send inbox notifications with optional APNs push delivery |