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.app

Authentication

All endpoints (except /health) require a Bearer token in the Authorization header:

Authorization: Bearer hlk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

Two token types are supported:

Prefix	Type	Access
`hla_`	API Token	Full access to all endpoints
`hlk_`	Integration Key	Scoped -- `activity:update` (default) or `activity:manage`

See Authentication for details on obtaining and managing tokens.

Activity State Machine

Activities follow a state machine with three states:

State	Description
`ENDED`	Inactive (default on creation)
`ONGOING`	Active Live Activity running on device
`PREEMPTED`	Server-evicted due to priority limits

State Transitions

Transitions are triggered via PATCH /activity/{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)
`PREEMPTED`	`ONGOING`	Push-to-start (restarts activity)
`ENDED`	`ENDED`	No push (no-op)

ℹ Info

PREEMPTED is server-internal and cannot be set via the API. It is applied automatically when the ONGOING activity limit is exceeded.

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

⚠ Warning

Exceeding the rate limit returns HTTP 429 Too Many Requests with {"error": "rate limit exceeded"}. Back off and retry after the limit window resets.

Endpoints

Section	Description
Authentication	Token management and user profile
Activities	Create, list, update, and delete activities
Integration Keys	Scoped keys for external services
Activity Sharing	Share activities with other users via share codes or pattern-based sharing