ドキュメントを開く +

API リファレンス

正式環境は https://push.breezelabs.dev、開発・結合テスト用は https://push-stg.breezelabs.dev です。Apple クライアントはそれぞれ Production / Sandbox の APNs Token を使います。Android はビルドに対応したサービスと Firebase 設定を使い、FCM に APNs の sandbox モードはありません。環境ごとにデータと認証情報を分離しています。登録と provider の提供状況は GET /v1/capabilities で確認してください。通常の利用者は通知を許可してリンクをコピーするだけで、以下の登録・管理 API は Breeze クライアントが呼び出します。Breeze はこのホスト型サービスとしてのみ提供され、セルフホストのサーバーはありません。すべてのエンドポイントは HTTPS のみ受け付けます。

1. 最初の通知を送信する#

他のシステムを経由する際に key が URL ログへ記録されることを避けるため、Webhook key はリクエストヘッダーで渡すことを推奨します。

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 クライアントが処理する画像 / アバターの URL です。APNs のネイティブな添付フィールドではありません
sound_url / soundUrl クライアントがダウンロードする音声の URL です。クライアント側の実装が必要です
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 の 3 条件すべてが必要です。

Android の通知フィールド#

送信先の API と Webhook key は共通です。FCM アダプターは平坦な文字列の data-only メッセージを送り、Android クライアントが履歴の保存と通知表示を行います。Google の notification、data.breeze、サーバーが指定する通知 channel は送りません。クライアントが level に応じて channel を選び、音と重要度は最終的にユーザーのシステム設定に従います。

フィールド Android の動作と制限
title、subtitle、message / body 文字列。少なくとも 1 つの表示用テキストに空白以外の文字が必要です
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 URL。画像とアイコンはクライアントが処理します
copy 通知のコピー操作でクリップボードにコピーするテキスト
sound default / system のみ。既存の channel の標準動作を使います
id 最大 128 文字の業務メッセージ ID。省略時はサーバーが生成し、クライアントの重複排除と削除に使います
data 最大 128 項目の平坦な string→string メタデータ。空の値は省略し、制御用キーと Google の予約キーは拒否します。未知の独自フィールドは現在、表示もクライアントの履歴モデルへの保存も行いません
ttl 0–2419200 秒。標準は 4 週間です。0 は即時配信の試行のみで、到達を保証しません
expiration_date 4 週間以内の将来を表す 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 は可変長の 16 進数 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 でも同じローテーション、失効、共有グループ管理 API を使いますが、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。共有リンクを削除します

1 つの共有リンクに登録できるのは最大 20 台です。グループの重複や同じ key の指定があっても、同じアドレスへの配信は 1 回です。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 とリンクを更新できます。1 つのインストールに保持できる専用ターゲットは最大 64 件です。アクティビティが終了したら、対応するターゲットを削除してください。Live Activity の scope は、start(push-to-start Token)または activity(特定の活動の update Token)が必須で、イベントの用途を入れ替えることはできません。DELETE /v1/devices/{id}/targets/{targetId} をデバイスの管理用認証情報で呼び出すと、そのターゲットを削除できます。

認識するタイプは、alert、background、liveactivity、controls、widgets、voip、pushtotalk、location、fileprovider、complication、mdm、accessory の 12 種類です。標準で有効なのは 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 binding が必要です。binding がない場合は、通常の App key にフォールバックしません。Accessory には iOS 26.5 や EU などの前提条件があります。各タイプには、アプリ側の対応も必要です。

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 を返した場合だけ、サーバーは認証を更新して最大 1 回再送します。タイムアウト、応答中の切断、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 を個別に確認します。無効な Android は中立表示、機能情報を取得できない場合や結果が不確かな場合は未確認です。GET /info はバージョンとドキュメントへの入口を返し、デバイスのアドレスや件数は公開しません。API の応答は Cache-Control:no-store です。

8. 制限#

項目 現在の制限
1 リクエスト 最大 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 をツールに取り込める形式で記述しています。