Zum Inhalt springen

Nachricht erstellen POST ​

Sende eine Push-Benachrichtigung an deine Geräte.

Endpunkt ​

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

Authentifizierung ​

Erforderlich

Füge einen dieser Header in deine Anfrage ein:

Anfrage ​

HeaderErforderlichBeschreibung
Content-Type✅application/json
Token✅Dein API-Schlüssel
Authorization✅Bearer <jwt-token>

* Einer der Header Token oder Authorization ist erforderlich

Body-Parameter ​

ParameterTypErforderlichBeschreibung
titlestring✅Titel der Benachrichtigung
messagestring✅Text der Benachrichtigung
application_idstring❌Anwendungs-TID, um die Nachricht zu kategorisieren
device_idstring❌Bestimmte Geräte-TID, weglassen für alle Geräte
levelstring | int❌Prioritätsstufe, die die Zustellung der Push-Benachrichtigung steuert. Akzeptiert einen Namen oder eine Zahl (-2..2). priority ist als Synonym erlaubt. Standardmäßig die Standardstufe der Anwendung, sonst default.
actionsarray❌Bis zu 3 Aktionsbuttons, die in der Benachrichtigung angezeigt werden. Siehe Aktionsbuttons.
send_atstring | int❌Zustellung zu einem bestimmten Zeitpunkt statt sofort. RFC3339, Unix-Timestamp oder YYYY-MM-DD HH:MM. Siehe Geplanter Versand.
delaystring❌Zustellung nach einer relativen Verzögerung — 30m, 2h oder reine Sekunden. Schließt send_at aus.

Aktionsbuttons ​

Jede Benachrichtigung kann bis zu 3 Aktionsbuttons enthalten. Sie funktionieren, egal ob die App geöffnet, im Hintergrund oder geschlossen ist. actions ist ein Array aus Objekten, im JSON-kodierten Zustand maximal 2048 Bytes groß (es wird innerhalb der Push-Benachrichtigung übertragen, die auf 4 KB begrenzt ist; ein langes message wird dafür gekürzt):

FeldTypErforderlichBeschreibung
typestring✅view (URL öffnen), http (HTTP-Anfrage senden) oder copy (Text in die Zwischenablage kopieren)
labelstring✅Button-Text, auf Android und iOS unverändert angezeigt
valuestring✅Hängt von type ab — siehe unten

value nach Typ:

  • view — die zu öffnende URL, z. B. "https://pocketalert.app".
  • http — ein JSON-String, der die Anfrage beschreibt: {"url":"https://…","method":"POST","headers":{…},"body":"…"}. Nur url ist erforderlich; method ist standardmäßig GET. Wird im Hintergrund direkt vom Gerät gesendet, ohne die App zu öffnen, daher können auch Hosts im lokalen Netzwerk des Handys erreicht werden. Schlägt die Anfrage fehl (Status außerhalb 2xx/3xx oder Netzwerkfehler), wird eine Benachrichtigung mit einem Erneut versuchen-Button angezeigt; sie wird nie automatisch wiederholt, sobald sie den Server möglicherweise erreicht hat.
  • copy — der wörtliche Text, der in die Zwischenablage gelegt wird.

Mensch im Entscheidungsprozess

Zwei http-Aktionen (z. B. Genehmigen / Ablehnen) ergeben ein Bedienfeld mit einem Tipp — ideal, um Aktionen von LLM-Agenten direkt aus der Benachrichtigung zu genehmigen.

Kostenpflichtiges Feature

Aktionsbuttons werden im kostenlosen Tarif entfernt: Die Nachricht wird ohne sie zugestellt, und actions wird nicht validiert.

Siehe Aktionsbuttons für Limits, Validierung und Webhook-Vorlagen.

Prioritätsstufen ​

StufeAliaseVerhalten
silentmin, -2Nur im Benachrichtigungscenter zugestellt — kein Ton und keine Vibration
low-1Leise, ohne Unterbrechung
defaultnormal, 0 (oder weggelassen)Standard-Banner + Ton
high1Zeitkritisch — durchbricht Fokus / geplante Zusammenfassung
criticalmax, urgent, 2Weckt das Gerät trotz Stummschalter und Nicht stören. Siehe Prioritätsstufen

WARNING

critical ist ein Feature des kostenpflichtigen Tarifs. Im kostenlosen Tarif wird es automatisch auf high herabgestuft. Ungültige Werte (unbekannter Name oder Zahl außerhalb des Bereichs) liefern 400.

Siehe Prioritätsstufen für das Verhalten jeder Stufe auf iOS und Android.

Geplanter Versand ​

Füge send_at oder delay hinzu — niemals beides — dann wird die Nachricht verschlüsselt bis zum Zustellzeitpunkt gespeichert, statt sofort gesendet zu werden.

ParameterAkzeptiertBeispiele
send_atRFC3339, Unix-Timestamp oder YYYY-MM-DD HH:MM2026-08-15T09:00:00Z, 1786867200
delayGo-Dauer oder reine Sekunden30m, 2h, 3600

Eine Zeit ohne Offset wird in deiner Konto-Zeitzone gelesen. Der Planungshorizont beträgt 30 Tage, und ein send_at in der Vergangenheit liefert 400 (mit 60 Sekunden Toleranz für Uhrabweichungen).

Geplante Anfragen liefern 201 mit "scheduled": true, status, deliver_at und deliver_at_utc statt einer zugestellten Nachricht. Liste sie mit GET /v1/messages/scheduled auf und storniere sie mit DELETE /v1/messages/scheduled/{tid} — siehe Geplanter Versand.

WARNING

Geplanter Versand ist ein Feature des kostenpflichtigen Tarifs. Anfragen im kostenlosen Tarif mit send_at oder delay liefern 403.

Beispielanfrage ​

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();

Antwort ​

Erfolgsantwort ​

201 Created

Nachricht erfolgreich erstellt

FeldTypBeschreibung
tidstringEindeutige Nachrichten-ID
titlestringTitel der Nachricht
messagestringText der Nachricht
applicationstringName der Anwendung (falls angegeben)
devicestringName des Zielgeräts
actionsarrayZurückgegebene Aktionsbuttons (nur wenn angegeben)
created_atstringZeitstempel der Erstellung
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"
}

Kontingent-Header ​

Antworten enthalten die heutige Nutzung des Tageslimits (entfällt in Tarifen ohne Limit):

HeaderBeschreibung
X-PA-Daily-LimitPro Tag erlaubte Nachrichten in deinem Tarif
X-PA-Daily-RemainingHeute verbleibende Nachrichten, nach dieser hier
X-PA-Daily-ResetUnix-Timestamp (Sekunden) des nächsten Zurücksetzens, 00:00 UTC

Fehlerantworten ​

StatusBeschreibung
400Bad Request — fehlender title oder message, ein ungültiges level oder, in kostenpflichtigen Tarifen, ungültige actions
401Unauthorized — ungültiger oder fehlender Token
403Forbidden — send_at oder delay im kostenlosen Tarif
404Not Found — application_id oder device_id existiert nicht
429Tageslimit erreicht — die Nachricht wurde weder gespeichert noch gesendet. Warte Retry-After Sekunden oder upgrade deinen Tarif. Siehe Tageslimits für Nachrichten.
json
{
  "error": "Validation failed",
  "details": {
    "title": ["The title field is required"]
  }
}

Tageslimit erreicht ​

Ist das heutige Kontingent aufgebraucht, wird die Nachricht abgelehnt — nicht in die Warteschlange gestellt — bis 00:00 UTC. Retry-After enthält die Sekunden bis zum Zurücksetzen.

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

Das Löschen von Nachrichten gibt kein Kontingent frei. Prüfe die heutige Nutzung mit GET /v1/messages/usage.

Pocket Alert Dokumentation