浏览文档 +

API 参考

正式地址:https://push.breezelabs.dev;联调地址:https://push-stg.breezelabs.dev。Apple 客户端分别使用 Production / Sandbox APNs Token;Android 使用对应构建的服务与 Firebase 配置,FCM 没有 APNs sandbox 模式。各环境的数据与凭据隔离,注册及 provider 开放状态以 GET /v1/capabilities 为准。普通用户只需允许通知并复制链接,以下注册与管理接口由 Breeze 客户端调用。Breeze 只以这个托管服务的形式运行,不支持自建服务器。所有接口都只接受 HTTPS。

1. 发送第一条通知#

推荐把 Webhook key 放在请求头,避免经过其他系统时进入 URL 日志:

cURL / Bash
curl https://push.breezelabs.dev/v1/send \
  -H 'Authorization: Bearer YOUR_WEBHOOK_KEY' \
  -H 'Content-Type: text/plain; charset=utf-8' \
  --data-binary '构建完成,可以查看结果了。'

也支持 App 复制出的完整 Webhook:POST /v1/{key};不指定 Content-Type 的纯文本及 curl -d 'Hello' 可用。JSON 发送:

cURL / Bash
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 以及 Bark 常见脚本路径 GET /{key}/{body}、/{key}/{title}/{body}、/{key}/{title}/{subtitle}/{body} 也可用。URL 的每段应单独编码,服务端只解码一次。+ 不会被误改为空格。

投递结果#

json
{"code":200,"message":"accepted","request_id":"UUID","data":{"accepted":1,"failed":0}}

accepted 表示投递服务(Apple APNs 或 Google FCM)接受请求,不代表手机已收到、显示或用户已读。部分成功返回 HTTP 207,data 包含 errors、retryable,必要时包含 outcome_unknown 与 retry_after_seconds;失效或未知链接另计入 unavailable_webhooks。不要把其余成功当作全部成功,也不要立即重发整个批次。全失败返回错误;request_id 可用于排查,服务端不回显 key、设备地址或正文。

2. 友好参数与 Apple 原始 Payload#

下表和 Apple 原始 payload 示例说明 Apple / APNs 行为;Android 仅支持下方明确列出的字段,不会把不支持的参数静默透传。

字段 类型 / 作用
message / body 字符串,通知正文
title、subtitle 字符串,标题、副标题
thread_id / group 字符串,通知分组
interruption_level / level passive、active、time-sensitive(兼容 timeSensitive)、critical
badge 0–99999 的整数;0 清空角标。支持仅角标推送
sound default、system、none 或客户端已包含的声音名;保留 .caf / .wav / .aiff,无后缀按 Bark 声音约定补 .caf。支持仅声音推送
volume 0–1,关键警报声音音量;0 保留
open_url / url 点击后打开的 HTTP(S) 链接
image_url / image、icon_url / icon 交给客户端处理的图片 / 头像地址,不是 APNs 原生附件字段
sound_url / soundUrl 交给客户端下载的声音地址;需要客户端实现
category、target_content_id、filter_criteria 对应 APS category / target-content-id / filter-criteria;依赖客户端注册的行为和 Focus Filter
relevance_score 0–1 的数字,普通通知的摘要排序权重
expiration_date 将来的 ISO 8601 日期时间;如 2027-01-01T00:00:00Z
apns_expiration UTC Unix 秒;0 表示 APNs 不存储;默认 24 小时。VoIP、Controls、PTT 默认 0
priority 通用值 1 / 5 / 10;background 严格 5,Live Activity 为 5 / 10,PTT 严格 10
collapse_id 最多 64 UTF-8 bytes,合并重复状态通知;不是“恰好一次”保证
push_type 默认 alert;其余类型必须匹配目标已登记的 Token kind,且由服务运营启用
data 自定义 JSON 对象,置于 APS 同级;不入库
payload Apple 原始 JSON payload 对象。可表达全部官方 APS 字段、alert 本地化和专用框架内容
device_key、device_keys /push 的脚本兼容字段;批量最多 20 个 key,解析后最多 20 个注册设备/目标
ciphertext、iv 客户端解密用密文及 IV;服务端不解密
markdown、copy、autocopy、call、isarchive、ttl、action、id、delete Bark 常见处理字段;依赖未来客户端对应处理器,保留协议能力。delete 要求 id,使用 background

字段名兼容大小写;同时提供友好别名与 Bark 字段时,Bark 字段优先。路径中的 key 或 Bearer key 覆盖 body 的目标;不能用 body 把已授权的单设备请求改投其他设备。

普通 alert 可以直接发送完整 Apple payload:

json
{
  "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"
  }
}

仅后台数据:{"push_type":"background","data":{"job_id":"42"}}。服务端生成 aps:{"content-available":1},不会加入 alert / sound / badge。系统可节流后台更新,不能承诺准时唤醒。

最终序列化 payload 按 UTF-8 bytes 校验:普通单播 4096,VoIP 单播 5120。请求 body 上限 16384 bytes。图片、音频和视频需要客户端 NSE 下载并生成附件;服务端不会代下载 URL。关键警报需 Apple entitlement、用户授权及 ALLOW_CRITICAL_ALERTS=true,三者齐备后才可使用。

Android 通知字段#

发送入口和 Webhook key 不变。FCM 适配器发送平铺字符串 data-only 消息,由 Android 客户端写入历史并显示通知;不发送 Google notification、data.breeze 或服务端指定的通知 channel。客户端根据 level 选择 channel,声音和重要性最终由用户的系统设置决定。

字段 Android 行为与限制
title、subtitle、message / body 字符串;至少一段非空白可见文本
markdown Markdown 正文字符串,不是布尔开关;不能与不同的非空 body 同传
thread_id / group 分组字符串
interruption_level / level active、passive、timeSensitive;time-sensitive 归一化为 timeSensitive
open_url / url、image_url / image、icon_url / icon 无内嵌凭据的 HTTPS 地址;图片与图标由客户端处理
copy 通知“复制”操作要复制的文本
sound 仅 default / system;使用现有 channel 的默认行为
id 最多 128 字符的业务消息 ID;未提供时服务端生成,供客户端去重与删除
data 最多 128 项的平铺 string→string 元数据;空值忽略,控制键与 Google 保留键拒绝;未知自定义字段当前不展示、不存入客户端历史模型
ttl 0–2419200 秒,默认四周;0 仅即时尝试,不保证送达
expiration_date 四周内的未来 ISO 8601 时间,转换为 TTL;不能与 ttl 同传
priority normal / high;可见 active / timeSensitive 默认 high,passive 与删除必须 normal
collapse_id / collapse_key 最多 64 UTF-8 bytes,合并待发消息;两个名称若同传必须相同,不提供恰好一次保证

badge、ciphertext、iv、自定义声音(含 sound=none)、Critical Alerts、Apple 原始 payload / APS 和 Apple 专用推送能力返回 422;其他未列入 Android 协议的字段也拒绝。Android 的 timeSensitive 是客户端 channel 选择,不具有 Apple Critical Alerts 权限。完整 Google HTTP v1 请求(含路由与配置字段)保守限制为 4096 UTF-8 bytes。

普通 push_type=background 返回 422 fcm_background_unsupported,不能用于静默同步。唯一后台操作为:

json
{"delete":1,"id":"previous-message-id"}

删除使用 background / normal,发给客户端的 data 只有 id、ts、delete;必须提供 id,不能混入显示内容或自定义 data,也不能显式指定 high。系统后台限制仍可能影响送达,不保证删除必达。

3. 设备注册与管理#

发送 key 为 5 字符类型前缀加 Base64URL(16 CSPRNG bytes),共 27 字符:设备 bz_d_、共享组 bz_g_、专用目标 bz_t_。management secret 独立生成至少 32 随机 bytes;installation ID 也随机生成。管理凭据只存 Keychain / Android 安全存储,不给脚本或消息发送方。服务端只保存凭据的 SHA-256 hash,并保存 APNs Token 或 FID 作为投递地址。

Apple 设备注册#

POST /v1/devices,Content-Type application/json:

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"
}

ID 为 16–128 个 URL-safe 字符,management secret 为 32–128 个 URL-safe 字符;发送 key 严格 27 字符、类型前缀匹配对应资源,格式为 ^bz_[dgt]_[A-Za-z0-9_-]{21}[AQgw]$。示例中的尖括号内容是占位符,实际凭据由客户端生成。APNs Token 是可变长度十六进制 bytes,不固定为 64 位。platform 为 ios 或 watchos;watchos 需要配置独立 Watch topic。

成功 HTTP 201:data:{key,webhook_url,send_url}。同一安装重复注册可刷新 Token、恢复失效 Token,也可在持有原管理凭据时更换链接。不同管理凭据不能抢占安装 ID;key 冲突返回 409 且事务回滚。平台身份不能在同一 installation ID 下互换。

Android 设备注册#

同样调用 POST /v1/devices。以下开发构建的占位示例发送到 https://push-stg.breezelabs.dev/v1/devices;正式构建应使用其服务器 providers.fcm.android_package 公布的包名。

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>",
  "platform":"android",
  "address_kind":"fcm_installation_id",
  "fid":"<22_BASE64URL_CHARACTERS_FROM_ONREGISTERED>",
  "app_id":"com.hiromoto.breezepush.stg"
}

fid 必须是 FCM SDK onRegistered 返回的 22 字符 Base64URL Firebase Installation ID,保留大小写;address_kind 只接受 fcm_installation_id,不接受 firebase_installation_id 或旧 registration token。app_id 是 Android applicationId / 包名,不是 1:…:android:… 形式的 Firebase App ID;必须匹配服务端配置,否则返回 422 app_mismatch。

Android 不接受 environment、device_token、token、apns_environment、project_id、firebase_project_id、application_id、package_name。Firebase 项目、凭据及投递包名仅由服务端绑定;FCM 没有 APNs environment。未启用返回 422 provider_not_enabled;配置或 OAuth 未就绪则注册失败,不写入设备。成功和同身份重复注册均返回 201,响应仍为 data:{key,webhook_url,send_url}。FID 和 app_id 匹配都不等于设备所有权证明,App Check / Play Integrity 尚未接入。

更新与撤销#

方法与路径 鉴权及作用
PUT /v1/devices/{id} Bearer management secret;Apple body 为 key、device_token、environment、platform;Android 为 key、platform=android、address_kind、fid、app_id。安装身份由 URL 与 Bearer 固定
POST /v1/devices/{id}/rotate Bearer management secret;body {"new_key":"bz_d_<NEW_22_RANDOM_CHARACTERS>"},新链接立即替换旧链接
DELETE /v1/devices/{id} Bearer management secret;撤销该安装、所有目标、链接和共享组成员关系

当前是否接收注册以 capabilities 的 registration_open 及 providers.fcm.registration_open 为准。Android 使用同样的 rotate、revoke 与共享组管理接口,不能登记 Apple 专用 targets。

POST /v1/channels 的 body 为 channel_id、独立 management_secret、key;生成一个共享 Webhook。可由未来客户端安全同步其管理身份;服务端不要求邮箱账户。

方法与路径 内容
PUT /v1/channels/{channelId}/devices/{installationId} Bearer channel management secret;body {"device_management_secret":"..."};需要同时证明两端所有权
DELETE /v1/channels/{channelId}/devices/{installationId} Bearer channel management secret;移除成员
POST /v1/channels/{channelId}/rotate Bearer channel management secret;body new_key
DELETE /v1/channels/{channelId} Bearer channel management secret;撤销共享链接

一个共享链接最多 20 台设备。重叠共享组或重复 key 只投递同一地址一次。Apple 成员可使用 alert / background,Android 成员仅支持 alert 与上述受控删除;所有已解析目标的参数、项目/包名与 provider 认证都在发送前校验,实际投递仍可能部分成功。跨平台批次应省略 provider 专属 priority(Apple 为 1/5/10,Android 为 normal/high)。共享组不自动广播 Live Activities;它与 Apple APNs broadcast channel 是两种机制。

5. Apple 专用 Token 目标#

普通 App Token 不能冒充 ActivityKit、WidgetKit、PushKit 等专用 Token。

POST /v1/devices/{installationId}/targets,Bearer device management secret:

json
{
  "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>"
}

成功返回此专用目标的 Webhook。同 ID 重复登记可更新该 Token 和链接;每个安装最多保留 64 个专用目标,活动结束后应撤销对应目标。Live Activity scope 必须为 start(push-to-start Token)或 activity(某个活动的 update Token);事件不能互换。DELETE /v1/devices/{id}/targets/{targetId} 用设备管理身份撤销该目标。

支持识别的 12 类:alert、background、liveactivity、controls、widgets、voip、pushtotalk、location、fileprovider、complication、mdm、accessory。默认仅启用 alert/background。voip、pushtotalk、location、fileprovider、complication、mdm、accessory 还要求运营批准:请求头 X-Provider-Admin 与服务端 secret 匹配。发送方不能覆盖 topic;topic 始终由目标平台和运营配置推导。

Live Activity 更新示例:

json
{"payload":{"aps":{"timestamp":1794614400,"event":"update","content-state":{"progress":0.6}}}}

timestamp 应为发送时的 Unix 秒。start 另外要求 attributes-type、attributes、alert;end 发送最终 content-state,可带 dismissal-date。ContentState / ActivityAttributes 必须匹配客户端定义。Controls 与 Widgets 使用 {"payload":{"aps":{"content-changed":true}}}。

MDM 仅接收 payload:{"mdm":"PushMagic"},需单独 MDM 证书 / topic / mTLS 绑定;没有绑定不会回退到普通 App key。Accessory 有 iOS 26.5 与 EU 等前提。各类型还需要 App 中对应的客户端支持。

GET /v1/capabilities 的 webhook_keys 描述当前 27 字符密钥协议;Apple push_types 分别返回 transport_implemented、server_enabled、client_required、verified_end_to_end。providers.fcm 单独返回 transport_implemented、operator_enabled、configured、server_enabled、registration_open、status、address_kinds、android_package、supported_push_types、supported_operations、unsupported_fields、client_constraints、verified_end_to_end。Android 的 canonical address_kinds 为 fcm_installation_id,supported_push_types 为 ["alert"],supported_operations 为 ["alert","delete"];真机未验收时 verified_end_to_end 保持 false。开关和配置状态不等于实际投递成功。Apple broadcast 与 Safari Web Push 仍未开放。

6. 错误与重试#

错误格式:{code,error,message,retryable,request_id},结果未知时可追加 outcome_unknown:true。常见 HTTP 状态:400 格式/字段问题;401 缺 Webhook;403 管理身份或准入不符;404 链接无有效设备;409 凭据冲突;413 过大;415 Content-Type 不支持;422 类型/能力不匹配、Apple environment_mismatch、Android app_mismatch 或 provider_not_enabled;426 官方 Bark App 注册不兼容;429 入口限流;502 provider 拒绝或投递结果未知;503 暂时不可用或配置/授权未就绪。

入口 429 默认 Retry-After: 60。FCM 上游限流或 5xx 可映射为 503,并保留 provider 的 Retry-After(FCM 限流至少 60 秒);其他可重试错误在无专属等待值时提供 Retry-After: 5。207 的等待值可能位于 data.retry_after_seconds。遵循实际响应,不要写死重试间隔。

仅当 APNs 明确报告 JWT 过期,或 FCM 明确返回 401 UNAUTHENTICATED 时,服务端最多刷新认证并重发一次;网络超时、断流和 5xx 不自动重投。FCM 请求已发出但无法确认响应时,返回 outcome_unknown:true、retryable:false(全失败在顶层,207 在 data);不能因为收到 Retry-After 就忽略未知结果并自动重发。任何“是否被接受未知”的失败都可能重复展示;collapse_id 不是恰好一次保证,207 也不能盲目重发整组。

APNs 410 / BadDeviceToken 会禁用失效地址;410 时间戳和更新版本检查防止旧请求误伤新注册。DeviceTokenNotForTopic 被视为运营配置错误,不删除用户 Token。FCM 仅在明确的 404 + FcmError UNREGISTERED 时停用地址;普通 404、INVALID_ARGUMENT、SENDER_ID_MISMATCH 或权限问题不会删除 FID。更新版本与 provider/地址/项目/包名共同校验,避免旧请求停用刷新后的地址。

7. 健康检查#

GET /ping:code 200 / message pong,不访问 D1。GET /healthz:存活检查。

GET /readyz 或 ?provider=apns 保留 Apple 行为:检查存储与 APNs 签名配置(正式为 Production,stg 为 Sandbox)。可用 environment 显式指定环境;未启用或未配置返回 503,未知 environment 返回 400,成功 data 包含 environment。

GET /readyz?provider=fcm 检查 D1 和真实 OAuth 授权;FCM 未启用、配置或授权未就绪时返回 503,传入 APNs environment 参数或未知 provider 均返回 400。成功 data 包含 provider=fcm、deployment 与 verified_end_to_end=false。它不发送推送,也不验证 Google 项目发送权限或手机展示;capabilities 的开关/配置字段同样不等于真机验收。

/readyz 与 /v1/capabilities 使用独立状态限流,各自每 IP / location 约 12 次/分钟,不消耗发送额度。可读状态页 /status/ 分别检查 APNs 与已启用的 Android / FCM;未启用显示中性状态,能力查询不可得或检查不确定时显示未知。GET /info 提供版本与文档入口,不暴露设备地址或数量。API 响应 Cache-Control:no-store。

8. 限制#

项目 当前限制
单次请求 最多 20 个 key / 解析后 20 个目标
HTTP 请求体 最多 16 KiB
标准 APNs payload 最多 4096 UTF-8 字节
FCM 请求 含路由与配置,最多 4096 UTF-8 字节
每个发送 key 每个 Cloudflare 节点约每分钟 60 次
单个公网 IP 每个节点约每分钟 120 次发送
就绪 / 能力查询 各自约每 IP / 节点每分钟 12 次
新注册 约每 IP / 节点每分钟 5 次

以上计数为按节点的近似值,不是严格的全局配额。遇到 429 请遵循实际的 Retry-After。OpenAPI 以可导入工具的格式描述同一套 API。