コンテンツへスキップ

プッシュ通知を作成 POST ​

デバイスにプッシュ通知を送信します。

エンドポイント ​

POST https://api.pocketalert.app/v1/messages

認証 ​

必須

リクエストに次のいずれかのヘッダーを含めてください:

  • Token: <your-api-key> — API キーから取得できます
  • Authorization: Bearer <jwt-token> — ログインから取得できます

リクエスト ​

ヘッダー ​

ヘッダー必須説明
Content-Type✅application/json
Token✅API キー
Authorization✅Bearer <jwt-token>

* Token または Authorization のいずれかが必須です

ボディパラメーター ​

パラメーター型必須説明
titlestring✅通知のタイトル
messagestring✅通知の本文
application_idstring❌メッセージを分類するためのアプリケーション TID
device_idstring❌特定のデバイス TID。省略すると全デバイスに送信されます
levelstring | int❌プッシュ通知の配信方法を制御する優先度レベル。名前または整数(-2..2)を指定できます。priority も同義語として使えます。省略時はアプリケーションの既定レベル、その後 default が使われます。
actionsarray❌通知に表示するアクションボタン(最大 3 つ)。アクションボタンを参照してください。
send_atstring | int❌即時ではなく指定した時刻に配信します。RFC3339、Unix タイムスタンプ、または YYYY-MM-DD HH:MM を指定できます。予約送信を参照してください。
delaystring❌相対的な遅延後に配信します(30m、2h、または秒数のみ)。send_at とは同時に指定できません。

アクションボタン ​

各通知には、アクションボタンを最大 3 個含められます。アプリが開いている場合、バックグラウンドの場合、終了している場合のいずれでも動作します。actions はオブジェクトの配列で、JSON エンコード後のサイズは最大 2048 バイトです(プッシュ通知全体の上限は 4 KB のため、この中に含まれます。長い message は、収まるように短縮されます):

フィールド型必須説明
typestring✅view(URL を開く)、http(HTTP リクエストを送信)、または copy(テキストをクリップボードにコピー)
labelstring✅ボタンのテキスト。Android と iOS でそのまま表示されます
valuestring✅type によって異なります。下記を参照してください

型ごとの value:

  • view — 開く URL。例: "https://pocketalert.app"
  • http — リクエストを記述した JSON 文字列: {"url":"https://…","method":"POST","headers":{…},"body":"…"}。url のみ必須で、method の既定値は GET です。アプリを開かずにデバイスからバックグラウンドで送信されるため、スマホのローカルネットワーク内のホストにも届きます。リクエストが失敗した場合(2xx/3xx 以外のステータスまたはネットワークエラー)、再試行ボタン付きの通知が表示されます。サーバーに届いた可能性がある場合は、自動的に再試行されることはありません。
  • copy — クリップボードに置くリテラルのテキスト。

人の確認を挟む

http アクションを 2 つ(例: 承認 / 却下)設定すると、ワンタップの操作パネルになります。LLM エージェントの操作を、通知から直接承認するのに最適です。

有料機能

無料プランではアクションボタンは削除されます。メッセージはボタンなしで配信され、actions の検証も行われません。

上限、検証、Webhook テンプレートについては アクションボタンを参照してください。

優先度レベル ​

レベル別名動作
silentmin, -2トレイにのみ配信され、音もバイブレーションもありません
low-1静かに届き、割り込みません
defaultnormal, 0(または省略時)標準のバナーと通知音
high1時間に敏感な通知です。集中モードや予約サマリーを突破して届きます
criticalmax, urgent, 2サイレントスイッチやおやすみモードを無視してデバイスを起動します。優先度レベルを参照してください

WARNING

critical は有料プランの機能です。無料プランでは自動的に high に格下げされます。無効な値(不明な名前や範囲外の整数)の場合は 400 が返されます。

各レベルが iOS と Android でどのように動作するかについては、優先度レベルを参照してください。

予約送信 ​

send_at または delay のどちらか一方を指定すると(両方の指定は不可)、メッセージは即時送信されず、暗号化されて配信時刻まで保存されます。

パラメーター指定できる形式例
send_atRFC3339、Unix タイムスタンプ、または YYYY-MM-DD HH:MM2026-08-15T09:00:00Z, 1786867200
delayGo 形式の期間、または秒数のみ30m, 2h, 3600

タイムゾーンのオフセットを含まない時刻は、アカウントのタイムゾーンとして解釈されます。予約可能な期間は 30 日までです。過去の send_at は 400 を返します(時計のずれを考慮し、60 秒の許容があります)。

予約送信のリクエストは、配信済みのメッセージではなく、201 と "scheduled": true、status、deliver_at、deliver_at_utc を返します。一覧は GET /v1/messages/scheduled で取得し、キャンセルは DELETE /v1/messages/scheduled/{tid} で行います。詳しくは予約送信を参照してください。

WARNING

予約送信は有料プランの機能です。無料プランで send_at または delay を使用したリクエストは 403 を返します。

リクエスト例 ​

bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Server Alert",
    "message": "CPU usage exceeded 90%",
    "application_id": "qm47b9pzxzxg",
    "level": "critical",
    "actions": [
      { "type": "view", "label": "Dashboard", "value": "https://status.example.com" },
      { "type": "http", "label": "Restart", "value": "{\"url\":\"https://ops.example.com/restart\",\"method\":\"POST\"}" },
      { "type": "copy", "label": "Copy ID", "value": "incident-4821" }
    ]
  }'
javascript
const response = await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Server Alert',
    message: 'CPU usage exceeded 90%',
    application_id: 'qm47b9pzxzxg'
  })
});

const data = await response.json();
console.log(data);
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/messages',
    headers={
        'Token': 'your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Server Alert',
        'message': 'CPU usage exceeded 90%',
        'application_id': 'qm47b9pzxzxg'
    }
)

print(response.json())
php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/messages', [
    'title' => 'Server Alert',
    'message' => 'CPU usage exceeded 90%',
    'application_id' => 'qm47b9pzxzxg',
]);

return $response->json();

レスポンス ​

成功時のレスポンス ​

201 Created

メッセージの作成に成功しました

フィールド型説明
tidstringメッセージの一意な識別子
titlestringメッセージのタイトル
messagestringメッセージの本文
applicationstringアプリケーション名(指定した場合)
devicestring送信先デバイス名
actionsarray送信されたアクションボタン(指定した場合のみ返されます)
created_atstring作成日時
json
{
  "tid": "jb4xw9elz28g",
  "title": "Server Alert",
  "message": "CPU usage exceeded 90%",
  "application": "Monitoring",
  "device": "iPhone",
  "actions": [
    { "type": "view", "label": "Dashboard", "value": "https://status.example.com" }
  ],
  "created_at": "18.01.2026 15:35:35"
}

クォータのヘッダー ​

レスポンスには、本日の 1 日の上限の使用状況が含まれます(無制限プランでは省略されます):

ヘッダー説明
X-PA-Daily-Limitお使いのプランで 1 日に送信できるメッセージ数
X-PA-Daily-Remaining今回のメッセージを含めた後、本日残りの送信可能数
X-PA-Daily-Reset次回リセット(00:00 UTC)の Unix タイムスタンプ(秒)

エラーレスポンス ​

ステータス説明
400不正なリクエスト — title または message の欠落、無効な level、または有料プランでの無効な actions
401認証エラー — トークンが無効または未指定です
403禁止 — 無料プランで send_at または delay を使用しています
404見つかりません — application_id または device_id が存在しません
4291 日の上限に到達 — メッセージは保存も送信もされていません。Retry-After の秒数だけ待つか、プランをアップグレードしてください。1 日のメッセージ上限を参照してください。
json
{
  "error": "Validation failed",
  "details": {
    "title": ["The title field is required"]
  }
}

1 日の上限に到達 ​

本日の上限を使い切ると、メッセージはキューに入れられず拒否されます。00:00 UTC までこの状態が続きます。Retry-After には、リセットまでの残り秒数が入ります。

http
HTTP/1.1 429 Too Many Requests
Retry-After: 30142
X-PA-Daily-Limit: 50
X-PA-Daily-Remaining: 0
X-PA-Daily-Reset: 1790035200
json
{
  "error": "Daily message limit reached (50/50). New messages are rejected until 00:00 UTC. Upgrade your plan to raise the limit.",
  "limit": 50,
  "used": 50,
  "resets_at": "2026-09-22T00:00:00Z",
  "upgrade_url": "https://pocketalert.app/pricing"
}

メッセージを削除しても、上限は回復しません。本日の使用状況は GET /v1/messages/usage で確認できます。

Pocket Alert ドキュメント