API reference
Production: https://push.breezelabs.dev. Integration testing: https://push-stg.breezelabs.dev. Apple clients use Production / Sandbox APNs tokens respectively; Android uses the service and Firebase configuration for its build, with no APNs sandbox mode in FCM. Environments have separate data and credentials. Check GET /v1/capabilities for registration and provider availability. Breeze runs only as this hosted service; there is no self-hosted server. Users only need to allow notifications and copy a link. The Breeze apps call the registration and management endpoints below. All endpoints require HTTPS.
1. Send your first notification#
Put the Webhook key in the request header to keep it out of URL logs in other systems:
curl https://push.breezelabs.dev/v1/send \
-H 'Authorization: Bearer YOUR_WEBHOOK_KEY' \
-H 'Content-Type: text/plain; charset=utf-8' \
--data-binary 'Build complete. You can check the results.'
You can also use the complete Webhook copied from the app: POST /v1/{key}. Plain text without a Content-Type, including curl -d 'Hello', is accepted. To send JSON:
curl https://push.breezelabs.dev/v1/send \
-H 'Authorization: Bearer YOUR_WEBHOOK_KEY' \
-H 'Content-Type: application/json' \
-d '{"title":"Build","message":"All checks passed","thread_id":"ci","interruption_level":"time-sensitive","open_url":"https://example.com/build/42"}'
GET /v1/{key}?message=Hello and common Bark script paths are also available: GET /{key}/{body}, /{key}/{title}/{body}, and /{key}/{title}/{subtitle}/{body}. Encode each URL segment separately. The server decodes each segment once and leaves + unchanged.
Delivery results#
{"code":200,"message":"accepted","request_id":"UUID","data":{"accepted":1,"failed":0}}
accepted means the delivery provider (Apple APNs or Google FCM) accepted the request, not that a phone received or displayed it, or that the user read it. Partial success returns HTTP 207 with errors and retryable in data, plus outcome_unknown and retry_after_seconds when applicable. Inactive or unknown links are counted separately in unavailable_webhooks. Success for the remaining targets is not complete success; do not immediately resend the whole batch. Complete failure returns an error. Use request_id for troubleshooting; the server does not echo keys, device addresses, or message bodies.
2. Friendly parameters and raw Apple payloads#
The table and raw Apple payload examples below describe Apple / APNs behavior. Android supports only the fields explicitly listed in its section; unsupported parameters are rejected rather than silently forwarded.
| Field | Type / purpose |
|---|---|
message / body |
String; notification body |
title, subtitle |
Strings; title and subtitle |
thread_id / group |
String; notification grouping |
interruption_level / level |
passive, active, time-sensitive (also accepts timeSensitive), or critical |
badge |
Integer from 0 to 99999; 0 clears the badge. Badge-only pushes are supported |
sound |
default, system, none, or a sound bundled with the client. .caf / .wav / .aiff extensions are preserved; names without an extension receive .caf following the Bark sound convention. Sound-only pushes are supported |
volume |
0–1; critical alert sound volume. A value of 0 is preserved |
open_url / url |
HTTP(S) link to open when the notification is tapped |
image_url / image, icon_url / icon |
Image / avatar URLs for the client to process; these are not native APNs attachment fields |
sound_url / soundUrl |
Sound URL for the client to download; requires client implementation |
category, target_content_id, filter_criteria |
Map to APS category / target-content-id / filter-criteria; depend on actions and Focus Filters registered by the client |
relevance_score |
Number from 0 to 1; ordering weight for standard notifications in a summary |
expiration_date |
Future ISO 8601 date and time, such as 2027-01-01T00:00:00Z |
apns_expiration |
UTC Unix seconds; 0 means APNs must not store the notification. Defaults to 24 hours; VoIP, Controls, and PTT default to 0 |
priority |
General values: 1 / 5 / 10. Background requires 5; Live Activity allows 5 / 10; PTT requires 10 |
collapse_id |
Up to 64 UTF-8 bytes; coalesces repeated state notifications. It does not guarantee exactly-once delivery |
push_type |
Defaults to alert. Other types must match the registered token kind of the target and be enabled by the service operator |
data |
Custom JSON object alongside APS; not stored |
payload |
Raw Apple JSON payload object. Supports all official APS fields, alert localization, and framework-specific content |
device_key, device_keys |
Script compatibility fields for /push; up to 20 keys per batch and 20 registered devices / targets after resolution |
ciphertext, iv |
Ciphertext and IV for client-side decryption; the server does not decrypt them |
markdown, copy, autocopy, call, isarchive, ttl, action, id, delete |
Common Bark processing fields. Protocol support is retained, but handling depends on corresponding future client handlers. delete requires id and uses background |
Field names are case-insensitive. When both a friendly alias and a Bark field are supplied, the Bark field takes precedence. A key in the path or Bearer header overrides targets in the body; a body cannot redirect an authorized single-device request to another device.
For a standard alert, you can send a complete Apple payload directly:
{
"payload": {
"aps": {
"alert": {"title-loc-key":"BUILD_DONE","title-loc-args":["Example"],"loc-key":"BUILD_BODY","loc-args":["42"]},
"badge": 0,
"category": "TASK_ACTIONS",
"target-content-id": "build-42",
"relevance-score": 0.8,
"filter-criteria": "work"
},
"job_id": "build-42"
}
}
For background data only: {"push_type":"background","data":{"job_id":"42"}}. The server generates aps:{"content-available":1} without alert / sound / badge. The operating system may throttle background updates, so a timely wake-up cannot be guaranteed.
The final serialized payload is checked by UTF-8 byte length: 4096 for standard unicast and 5120 for VoIP unicast. The request body limit is 16384 bytes. Images, audio, and video require a client Notification Service Extension (NSE) to download the media and create attachments; the server does not download URLs on the client's behalf. Critical Alerts require an Apple entitlement, user authorization, and ALLOW_CRITICAL_ALERTS=true; all three must be in place.
Android notification fields#
Send endpoints and Webhook keys are unchanged. The FCM adapter sends flat string data-only messages; the Android client writes history and displays notifications. It does not send a Google notification, data.breeze, or a server-selected notification channel. The client selects a channel by level; the user's system settings ultimately control sound and importance.
| Field | Android behavior and limits |
|---|---|
title, subtitle, message / body |
Strings; at least one visible text field must contain non-whitespace text |
markdown |
Markdown body text, not a boolean flag; cannot accompany a different nonempty body |
thread_id / group |
Grouping string |
interruption_level / level |
active, passive, or timeSensitive; time-sensitive normalizes to timeSensitive |
open_url / url, image_url / image, icon_url / icon |
HTTPS URLs without embedded credentials; the client handles images and icons |
copy |
Text to copy when the notification's copy action is used |
sound |
Only default / system; uses the existing channel's default behavior |
id |
Application message ID, up to 128 characters; generated by the server if omitted, for client deduplication and deletion |
data |
Flat string-to-string metadata, up to 128 entries; empty values are omitted, control and Google-reserved keys are rejected. Unknown custom fields are currently neither displayed nor stored in the client's history model |
ttl |
0–2419200 seconds; defaults to four weeks. 0 attempts immediate delivery only, without a delivery guarantee |
expiration_date |
Future ISO 8601 time within four weeks, converted to TTL; mutually exclusive with ttl |
priority |
normal / high; visible active / timeSensitive alerts default to high. Passive and deletion messages require normal |
collapse_id / collapse_key |
Up to 64 UTF-8 bytes; coalesces pending messages. If both names are supplied they must match; this is not an exactly-once guarantee |
badge, ciphertext, iv, custom sounds (including sound=none), Critical Alerts, raw Apple payload / APS, and dedicated Apple push capabilities return 422. Other fields outside the Android protocol are also rejected. Android timeSensitive selects a client channel; it does not grant Apple Critical Alerts privileges. The complete Google HTTP v1 request, including routing and configuration fields, has a conservative 4096 UTF-8 byte limit.
A normal push_type=background returns 422 fcm_background_unsupported; it cannot perform silent synchronization. The only background operation is:
{"delete":1,"id":"previous-message-id"}
Deletion uses background / normal, with only id, ts, and delete in the data sent to the client. An id is required; display content, custom data, and explicit high priority are rejected. System background restrictions may still prevent delivery, so deletion is not guaranteed.
3. Device registration and management#
Send keys consist of a 5-character type prefix and Base64URL(16 CSPRNG bytes), for 27 characters total: bz_d_ for devices, bz_g_ for shared groups, and bz_t_ for dedicated targets. Generate an independent management secret with at least 32 random bytes and a random installation ID. Keep management credentials in Keychain / Android secure storage; do not give them to scripts or message senders. The server stores only SHA-256 hashes of credentials and retains the APNs token or FID as a delivery address.
Apple device registration#
POST /v1/devices, with Content-Type application/json:
{
"installation_id":"random-installation-id-at-least-16-chars",
"management_secret":"INDEPENDENT_RANDOM_MANAGEMENT_SECRET_32_BYTES",
"key":"bz_d_<22_RANDOM_BASE64URL_CHARACTERS>",
"device_token":"APNS_HEXADECIMAL_TOKEN_BYTES",
"environment":"sandbox",
"platform":"ios"
}
IDs must contain 16–128 URL-safe characters, and management secrets 32–128 URL-safe characters. Send keys must be exactly 27 characters with the prefix matching the resource type; the pattern is ^bz_[dgt]_[A-Za-z0-9_-]{21}[AQgw]$. Angle-bracketed text in the example is a placeholder; the client generates the actual credentials. APNs tokens are variable-length hexadecimal bytes, not fixed at 64 characters. platform is ios or watchos; watchos requires a separately configured Watch topic.
Success returns HTTP 201 with data:{key,webhook_url,send_url}. Registering the same installation again can refresh its token, reactivate an invalidated token, or change the link when the original management credential is provided. A different management credential cannot claim an existing installation ID. A key conflict returns 409 and rolls back the transaction. The platform identity cannot change under the same installation ID.
Android device registration#
Use the same POST /v1/devices endpoint. Send this development-build placeholder example to https://push-stg.breezelabs.dev/v1/devices. Production builds must use the package reported by their server in providers.fcm.android_package.
{
"installation_id":"random-installation-id-at-least-16-chars",
"management_secret":"INDEPENDENT_RANDOM_MANAGEMENT_SECRET_32_BYTES",
"key":"bz_d_<22_RANDOM_BASE64URL_CHARACTERS>",
"platform":"android",
"address_kind":"fcm_installation_id",
"fid":"<22_BASE64URL_CHARACTERS_FROM_ONREGISTERED>",
"app_id":"com.hiromoto.breezepush.stg"
}
fid must be the case-sensitive, 22-character Base64URL Firebase Installation ID returned by the FCM SDK's onRegistered callback. address_kind accepts only fcm_installation_id, not firebase_installation_id or a legacy registration token. app_id is the Android applicationId / package name, not a Firebase App ID such as 1:…:android:…; it must match server configuration or registration returns 422 app_mismatch.
Android rejects environment, device_token, token, apns_environment, project_id, firebase_project_id, application_id, and package_name. The server alone binds the Firebase project, credentials, and delivery package. FCM has no APNs environment. Disabled FCM returns 422 provider_not_enabled; unavailable configuration or OAuth causes registration to fail without storing a device. Successful and repeated registrations with the same identity both return 201 with data:{key,webhook_url,send_url}. Neither a FID nor a matching app_id proves device ownership; App Check / Play Integrity is not integrated yet.
Refresh and revoke#
| Method and path | Authentication and purpose |
|---|---|
PUT /v1/devices/{id} |
Bearer management secret. Apple body: key, device_token, environment, platform. Android body: key, platform=android, address_kind, fid, app_id. The URL and Bearer credential fix the installation identity |
POST /v1/devices/{id}/rotate |
Bearer management secret; body {"new_key":"bz_d_<NEW_22_RANDOM_CHARACTERS>"} immediately replaces the old link with the new one |
DELETE /v1/devices/{id} |
Bearer management secret; revokes the installation, all its targets and links, and shared-group memberships |
Check capabilities registration_open and providers.fcm.registration_open for current admission status. Android uses the same rotation, revocation, and group-management endpoints but cannot register dedicated Apple targets.
4. Shared links for multiple devices#
POST /v1/channels takes channel_id, an independent management_secret, and key in the body to create a shared Webhook. Future clients can securely synchronize its management identity. The server does not require an email account.
| Method and path | Details |
|---|---|
PUT /v1/channels/{channelId}/devices/{installationId} |
Bearer channel management secret; body {"device_management_secret":"..."}; ownership of both resources must be proven |
DELETE /v1/channels/{channelId}/devices/{installationId} |
Bearer channel management secret; removes a member |
POST /v1/channels/{channelId}/rotate |
Bearer channel management secret; body contains new_key |
DELETE /v1/channels/{channelId} |
Bearer channel management secret; revokes the shared link |
A shared link can contain up to 20 devices. Overlapping groups and duplicate keys result in one delivery to the same address. Apple members can receive alert / background; Android members support only alert and the controlled deletion described above. Parameters, project/package bindings, and provider authentication for all resolved targets are validated before delivery, although delivery itself can still partially succeed. Omit provider-specific priority in mixed-platform batches: Apple uses 1/5/10, Android normal/high. Shared groups do not automatically broadcast Live Activities; they are separate from Apple APNs broadcast channels.
5. Dedicated Apple token targets#
An ordinary App token cannot stand in for an ActivityKit, WidgetKit, PushKit, or other dedicated token.
POST /v1/devices/{installationId}/targets, with Bearer device management secret:
{
"target_id":"random-target-id-at-least-16-chars",
"kind":"liveactivity",
"scope":"activity",
"token":"FRAMEWORK_SPECIFIC_HEXADECIMAL_TOKEN",
"environment":"sandbox",
"key":"bz_t_<22_RANDOM_BASE64URL_CHARACTERS>"
}
Success returns a Webhook for this dedicated target. Registering the same ID again can update its token and link. Each installation can retain up to 64 dedicated targets; revoke a target when its activity ends. A Live Activity scope must be start (push-to-start token) or activity (update token for a specific activity); their events are not interchangeable. Use DELETE /v1/devices/{id}/targets/{targetId} with the device management identity to revoke a target.
The server recognizes 12 types: alert, background, liveactivity, controls, widgets, voip, pushtotalk, location, fileprovider, complication, mdm, and accessory. Only alert/background are enabled by default. voip, pushtotalk, location, fileprovider, complication, mdm, and accessory also require operator approval: the X-Provider-Admin request header must match the server secret. Senders cannot override the topic; it is always derived from the target platform and operator configuration.
Example Live Activity update:
{"payload":{"aps":{"timestamp":1794614400,"event":"update","content-state":{"progress":0.6}}}}
timestamp should be the current Unix time in seconds when sending. start also requires attributes-type, attributes, and alert. end sends the final content-state and may include dismissal-date. ContentState / ActivityAttributes must match the client definitions. Controls and Widgets use {"payload":{"aps":{"content-changed":true}}}.
MDM only accepts payload:{"mdm":"PushMagic"} and requires a separate MDM certificate / topic / mTLS binding. Without that binding, it does not fall back to the normal App key. Accessory requires iOS 26.5 and conditions including EU availability. Each type also needs matching client support in the app.
The webhook_keys section of GET /v1/capabilities describes the current 27-character key contract. Apple push_types separately report transport_implemented, server_enabled, client_required, and verified_end_to_end. providers.fcm separately reports transport_implemented, operator_enabled, configured, server_enabled, registration_open, status, address_kinds, android_package, supported_push_types, supported_operations, unsupported_fields, client_constraints, and verified_end_to_end. Android canonical address_kinds is fcm_installation_id, supported_push_types is ["alert"], and supported_operations is ["alert","delete"]. verified_end_to_end remains false until real-device acceptance testing. Enablement and configuration flags do not prove successful delivery. Apple broadcast and Safari Web Push remain unavailable.
6. Errors and retries#
Error format: {code,error,message,retryable,request_id}, with outcome_unknown:true when applicable. Common HTTP statuses: 400 for malformed data / fields; 401 for a missing Webhook; 403 for invalid management identity or admission; 404 for no active devices; 409 for conflicting credentials; 413 for oversized content; 415 for unsupported Content-Type; 422 for type / capability mismatch, Apple environment_mismatch, Android app_mismatch, or provider_not_enabled; 426 for incompatible official Bark App registration; 429 for entry-point rate limiting; 502 for provider rejection or an unknown delivery outcome; and 503 for temporary unavailability or configuration / authorization not ready.
Entry-point 429 defaults to Retry-After: 60. FCM upstream rate limiting or 5xx may map to 503 with the provider's Retry-After preserved (at least 60 seconds for FCM rate limiting). Other retryable errors use Retry-After: 5 when no specific delay is available. For 207, the delay may appear as data.retry_after_seconds. Follow the actual response rather than hard-coding an interval.
The server refreshes authentication and resends at most once only when APNs explicitly reports an expired JWT or FCM explicitly returns 401 UNAUTHENTICATED. Network timeouts, interrupted responses, and 5xx do not trigger automatic redelivery. If an FCM request was sent but its response cannot be confirmed, the API returns outcome_unknown:true and retryable:false (at the top level for complete failure, in data for 207). A Retry-After value must not override an unknown outcome and trigger automatic resending. Any failure with unknown acceptance may lead to duplicates; collapse_id is not an exactly-once guarantee, and 207 must not trigger a blind retry of the whole group.
APNs 410 / BadDeviceToken disables an invalid address. The 410 timestamp and update-version checks protect fresh registrations from old requests. DeviceTokenNotForTopic is an operator configuration error and does not delete the user's token. FCM disables an address only for an explicit 404 + FcmError UNREGISTERED; ordinary 404, INVALID_ARGUMENT, SENDER_ID_MISMATCH, or permission errors do not delete a FID. Update-version and provider/address/project/package checks prevent old requests from disabling refreshed addresses.
7. Health checks#
GET /ping returns code 200 / message pong without accessing D1. GET /healthz is a liveness check.
GET /readyz or ?provider=apns retains Apple behavior: check storage and APNs signing configuration (Production on production, Sandbox on stg). An environment parameter can explicitly select an environment. Disabled or missing configuration returns 503; an unknown environment returns 400. Successful data includes environment.
GET /readyz?provider=fcm checks D1 and real OAuth authorization. Disabled FCM or unavailable configuration / authorization returns 503. Supplying an APNs environment parameter or an unknown provider returns 400. Successful data includes provider=fcm, deployment, and verified_end_to_end=false. It sends no push and does not verify Google project send permission or phone presentation; capability enablement / configuration flags do not establish real-device verification either.
/readyz and /v1/capabilities have independent status rate limits, each about 12 requests per minute per IP / location, without consuming the send quota. The readable /status/ page checks APNs and enabled Android / FCM independently. Disabled Android is neutral; unavailable capabilities or uncertain checks are unknown. GET /info provides version and documentation links without exposing device addresses or counts. API responses use Cache-Control:no-store.
8. Limits#
| Item | Current limit |
|---|---|
| One request | Up to 20 keys / 20 resolved targets |
| HTTP request body | Up to 16 KiB |
| Standard APNs payload | Up to 4096 UTF-8 bytes |
| FCM request | Up to 4096 UTF-8 bytes, including routing and configuration |
| Each send key | About 60 requests per minute per Cloudflare location |
| One public IP | About 120 send requests per minute per location |
| Readiness / capability queries | About 12 requests per minute per IP / location each |
| New registrations | About 5 per IP / location per minute |
These counters are approximate and per location, not strict global quotas. Follow the actual Retry-After on 429. OpenAPI describes the same API for import into tools.