Referência da API

A API do PushWard é uma API REST para gerenciar Live Activities no iOS 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

Tokens 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)

ℹ Informação

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

⚠ Aviso

HTTP 429 Too Many Requests is returned in two cases — distinguish them via the code field on the application/problem+json body:

code: "rate_limit.exceeded" — per-IP request rate limit (the table above). Transient; back off using Retry-After (typically a few seconds) and retry.
code: "quota.exceeded" — authenticated user's free-tier monthly allowance is exhausted (500 notifications/month + 250 Live Activity updates/month, calendar-month UTC reset). The body includes kind, used, limit, and reset_at; Retry-After is the seconds until the quota resets. Retrying before reset_at on the free tier will keep failing — surface an upgrade prompt instead.

See Errors for the full Problem Details shape and a quota.exceeded example response.

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
Widgets	Create, update, and delete Home Screen widgets
Email	Send transactional email to verified recipients