Nachricht erstellen POST
Sende eine Push-Benachrichtigung an deine Geräte.
Endpunkt
POST https://api.pocketalert.app/v1/messagesAuthentifizierung
Erforderlich
Füge einen dieser Header in deine Anfrage ein:
Token: <your-api-key>— Hol ihn dir unter API-SchlüsselAuthorization: Bearer <jwt-token>— Aus Anmeldung
Anfrage
Header
| Header | Erforderlich | Beschreibung |
|---|---|---|
Content-Type | ✅ | application/json |
Token | ✅ | Dein API-Schlüssel |
Authorization | ✅ | Bearer <jwt-token> |
* Einer der Header Token oder Authorization ist erforderlich
Body-Parameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
title | string | ✅ | Titel der Benachrichtigung |
message | string | ✅ | Text der Benachrichtigung |
application_id | string | ❌ | Anwendungs-TID, um die Nachricht zu kategorisieren |
device_id | string | ❌ | Bestimmte Geräte-TID, weglassen für alle Geräte |
level | string | 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. |
actions | array | ❌ | Bis zu 3 Aktionsbuttons, die in der Benachrichtigung angezeigt werden. Siehe Aktionsbuttons. |
send_at | string | int | ❌ | Zustellung zu einem bestimmten Zeitpunkt statt sofort. RFC3339, Unix-Timestamp oder YYYY-MM-DD HH:MM. Siehe Geplanter Versand. |
delay | string | ❌ | 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):
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
type | string | ✅ | view (URL öffnen), http (HTTP-Anfrage senden) oder copy (Text in die Zwischenablage kopieren) |
label | string | ✅ | Button-Text, auf Android und iOS unverändert angezeigt |
value | string | ✅ | 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":"…"}. Nururlist erforderlich;methodist standardmäßigGET. 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
| Stufe | Aliase | Verhalten |
|---|---|---|
silent | min, -2 | Nur im Benachrichtigungscenter zugestellt — kein Ton und keine Vibration |
low | -1 | Leise, ohne Unterbrechung |
default | normal, 0 (oder weggelassen) | Standard-Banner + Ton |
high | 1 | Zeitkritisch — durchbricht Fokus / geplante Zusammenfassung |
critical | max, urgent, 2 | Weckt 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.
| Parameter | Akzeptiert | Beispiele |
|---|---|---|
send_at | RFC3339, Unix-Timestamp oder YYYY-MM-DD HH:MM | 2026-08-15T09:00:00Z, 1786867200 |
delay | Go-Dauer oder reine Sekunden | 30m, 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
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" }
]
}'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);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())$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
| Feld | Typ | Beschreibung |
|---|---|---|
tid | string | Eindeutige Nachrichten-ID |
title | string | Titel der Nachricht |
message | string | Text der Nachricht |
application | string | Name der Anwendung (falls angegeben) |
device | string | Name des Zielgeräts |
actions | array | Zurückgegebene Aktionsbuttons (nur wenn angegeben) |
created_at | string | Zeitstempel der Erstellung |
{
"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):
| Header | Beschreibung |
|---|---|
X-PA-Daily-Limit | Pro Tag erlaubte Nachrichten in deinem Tarif |
X-PA-Daily-Remaining | Heute verbleibende Nachrichten, nach dieser hier |
X-PA-Daily-Reset | Unix-Timestamp (Sekunden) des nächsten Zurücksetzens, 00:00 UTC |
Fehlerantworten
| Status | Beschreibung |
|---|---|
400 | Bad Request — fehlender title oder message, ein ungültiges level oder, in kostenpflichtigen Tarifen, ungültige actions |
401 | Unauthorized — ungültiger oder fehlender Token |
403 | Forbidden — send_at oder delay im kostenlosen Tarif |
404 | Not Found — application_id oder device_id existiert nicht |
429 | Tageslimit erreicht — die Nachricht wurde weder gespeichert noch gesendet. Warte Retry-After Sekunden oder upgrade deinen Tarif. Siehe Tageslimits für Nachrichten. |
{
"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/1.1 429 Too Many Requests
Retry-After: 30142
X-PA-Daily-Limit: 50
X-PA-Daily-Remaining: 0
X-PA-Daily-Reset: 1790035200{
"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.