Créer un message POST
Envoyez une notification push à vos appareils.
Point de terminaison
POST https://api.pocketalert.app/v1/messagesAuthentification
Obligatoire
Incluez l’un de ces en-têtes dans votre requête :
Requête
En-têtes
| En-tête | Obligatoire | Description |
|---|---|---|
Content-Type | ✅ | application/json |
Token | ✅ | Votre clé API |
Authorization | ✅ | Bearer <jwt-token> |
* L’un des en-têtes Token ou Authorization est obligatoire
Paramètres du corps
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
title | string | ✅ | Titre de la notification |
message | string | ✅ | Texte du corps de la notification |
application_id | string | ❌ | TID de l’application pour classer le message |
device_id | string | ❌ | TID d’un appareil précis, à omettre pour tous les appareils |
level | string | int | ❌ | Niveau de priorité contrôlant la remise de la notification push. Accepte un nom ou un entier (-2..2). priority est accepté comme synonyme. Par défaut, le niveau par défaut de l’application, puis default. |
actions | array | ❌ | Jusqu’à 3 boutons d’action affichés sur la notification. Voir Boutons d’action. |
send_at | string | int | ❌ | Remise à un moment précis au lieu d’immédiatement. RFC3339, horodatage Unix ou YYYY-MM-DD HH:MM. Voir Envoi programmé. |
delay | string | ❌ | Remise après un délai relatif : 30m, 2h ou un nombre de secondes. Incompatible avec send_at. |
Boutons d’action
Chaque notification peut comporter jusqu’à 3 boutons d’action. Ils fonctionnent que l’application soit ouverte, en arrière-plan ou fermée. actions est un tableau d’objets, d’au plus 2048 octets une fois encodé en JSON (il voyage dans la notification push, limitée à 4 Ko ; un message long est raccourci pour faire de la place) :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
type | string | ✅ | view (ouvrir une URL), http (déclencher une requête HTTP) ou copy (copier un texte dans le presse-papiers) |
label | string | ✅ | Texte du bouton, affiché tel quel sur Android et iOS |
value | string | ✅ | Dépend de type, voir ci-dessous |
value selon le type :
view— l’URL à ouvrir, par exemple"https://pocketalert.app".http— une chaîne JSON décrivant la requête :{"url":"https://…","method":"POST","headers":{…},"body":"…"}. Seulurlest obligatoire ;methodvautGETpar défaut. La requête part de l’appareil en arrière-plan, sans ouvrir l’application, et peut donc atteindre des hôtes du réseau local du téléphone. Si la requête échoue (statut autre que 2xx/3xx ou erreur réseau), une notification avec un bouton Réessayer s’affiche ; elle n’est jamais relancée automatiquement une fois qu’elle a pu atteindre le serveur.copy— le texte littéral placé dans le presse-papiers.
Validation humaine
Deux actions http (par exemple Approuver / Refuser) forment un panneau de contrôle en un geste, idéal pour approuver directement depuis la notification les actions d’agents LLM.
Fonctionnalité payante
Les boutons d’action sont retirés sur l’offre gratuite : le message est remis sans eux, et actions n’est pas validé.
Consultez Boutons d’action pour les limites, la validation et les modèles de webhooks.
Niveaux de priorité
| Niveau | Alias | Comportement |
|---|---|---|
silent | min, -2 | Remis dans le centre de notifications uniquement, sans son ni vibration |
low | -1 | Discret, sans interruption |
default | normal, 0 (ou omis) | Bannière et son standard |
high | 1 | Urgent selon le temps — passe outre Concentration / le résumé programmé |
critical | max, urgent, 2 | Réveille l’appareil malgré le interrupteur silencieux et Ne pas déranger. Voir Niveaux de priorité |
WARNING
critical est une fonctionnalité des offres payantes. Sur l’offre gratuite, il est automatiquement ramené à high. Les valeurs invalides (nom inconnu ou entier hors plage) renvoient 400.
Consultez Niveaux de priorité pour le comportement de chaque niveau sur iOS et Android.
Envoi programmé
Ajoutez send_at ou delay — jamais les deux — et le message est stocké chiffré jusqu’à son heure d’envoi, au lieu d’être envoyé immédiatement.
| Paramètre | Accepte | Exemples |
|---|---|---|
send_at | RFC3339, horodatage Unix ou YYYY-MM-DD HH:MM | 2026-08-15T09:00:00Z, 1786867200 |
delay | Durée au format Go ou nombre de secondes | 30m, 2h, 3600 |
Une heure sans décalage horaire est interprétée dans le fuseau horaire de votre compte. L’horizon est de 30 jours, et un send_at passé renvoie 400 (avec une tolérance de 60 secondes pour les écarts d’horloge).
Les requêtes programmées renvoient 201 avec "scheduled": true, status, deliver_at et deliver_at_utc au lieu d’un message remis. Listez-les avec GET /v1/messages/scheduled et annulez-les avec DELETE /v1/messages/scheduled/{tid} — voir Envoi programmé.
WARNING
L’envoi programmé est une fonctionnalité des offres payantes. Les requêtes de l’offre gratuite utilisant send_at ou delay renvoient 403.
Exemple de requête
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();Réponse
Réponse de succès
201 Created
Message créé avec succès
| Champ | Type | Description |
|---|---|---|
tid | string | Identifiant unique du message |
title | string | Titre du message |
message | string | Corps du message |
application | string | Nom de l’application (si indiqué) |
device | string | Nom de l’appareil cible |
actions | array | Boutons d’action renvoyés (uniquement si fournis) |
created_at | string | Horodatage de création |
{
"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"
}En-têtes de quota
Les réponses incluent l’utilisation actuelle de la limite quotidienne (omis sur les offres sans limite) :
| En-tête | Description |
|---|---|
X-PA-Daily-Limit | Messages autorisés par jour sur votre offre |
X-PA-Daily-Remaining | Messages restants aujourd’hui, après celui-ci |
X-PA-Daily-Reset | Horodatage Unix (secondes) de la prochaine réinitialisation, 00:00 UTC |
Réponses d’erreur
| Statut | Description |
|---|---|
400 | Requête incorrecte — title ou message manquant, level invalide ou, sur les offres payantes, actions invalides |
401 | Non autorisé — jeton invalide ou manquant |
403 | Interdit — send_at ou delay sur une offre gratuite |
404 | Introuvable — application_id ou device_id n’existe pas |
429 | Limite quotidienne atteinte — le message n’a pas été stocké ni envoyé. Attendez Retry-After secondes ou passez à une offre supérieure. Voir Limites quotidiennes de messages. |
{
"error": "Validation failed",
"details": {
"title": ["The title field is required"]
}
}Limite quotidienne atteinte
Lorsque le quota du jour est épuisé, le message est rejeté — et non mis en file d’attente — jusqu’à 00:00 UTC. Retry-After indique le nombre de secondes restantes avant la réinitialisation.
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"
}La suppression de messages ne libère pas de quota. Vérifiez l’utilisation du jour avec GET /v1/messages/usage.