Aller au contenu

Créer un message POST ​

Envoyez une notification push à vos appareils.

Point de terminaison ​

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

Authentification ​

Obligatoire

Incluez l’un de ces en-têtes dans votre requête :

  • Token: <your-api-key> — Obtenez-la depuis Clés API
  • Authorization: Bearer <jwt-token> — Depuis Connexion

Requête ​

En-têtes ​

En-têteObligatoireDescription
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ètreTypeObligatoireDescription
titlestring✅Titre de la notification
messagestring✅Texte du corps de la notification
application_idstring❌TID de l’application pour classer le message
device_idstring❌TID d’un appareil précis, à omettre pour tous les appareils
levelstring | 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.
actionsarray❌Jusqu’à 3 boutons d’action affichés sur la notification. Voir Boutons d’action.
send_atstring | int❌Remise à un moment précis au lieu d’immédiatement. RFC3339, horodatage Unix ou YYYY-MM-DD HH:MM. Voir Envoi programmé.
delaystring❌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) :

ChampTypeObligatoireDescription
typestring✅view (ouvrir une URL), http (déclencher une requête HTTP) ou copy (copier un texte dans le presse-papiers)
labelstring✅Texte du bouton, affiché tel quel sur Android et iOS
valuestring✅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":"…"}. Seul url est obligatoire ; method vaut GET par 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é ​

NiveauAliasComportement
silentmin, -2Remis dans le centre de notifications uniquement, sans son ni vibration
low-1Discret, sans interruption
defaultnormal, 0 (ou omis)Bannière et son standard
high1Urgent selon le temps — passe outre Concentration / le résumé programmé
criticalmax, urgent, 2Ré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ètreAccepteExemples
send_atRFC3339, horodatage Unix ou YYYY-MM-DD HH:MM2026-08-15T09:00:00Z, 1786867200
delayDurée au format Go ou nombre de secondes30m, 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 ​

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

Réponse ​

Réponse de succès ​

201 Created

Message créé avec succès

ChampTypeDescription
tidstringIdentifiant unique du message
titlestringTitre du message
messagestringCorps du message
applicationstringNom de l’application (si indiqué)
devicestringNom de l’appareil cible
actionsarrayBoutons d’action renvoyés (uniquement si fournis)
created_atstringHorodatage de création
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"
}

En-têtes de quota ​

Les réponses incluent l’utilisation actuelle de la limite quotidienne (omis sur les offres sans limite) :

En-têteDescription
X-PA-Daily-LimitMessages autorisés par jour sur votre offre
X-PA-Daily-RemainingMessages restants aujourd’hui, après celui-ci
X-PA-Daily-ResetHorodatage Unix (secondes) de la prochaine réinitialisation, 00:00 UTC

Réponses d’erreur ​

StatutDescription
400Requête incorrecte — title ou message manquant, level invalide ou, sur les offres payantes, actions invalides
401Non autorisé — jeton invalide ou manquant
403Interdit — send_at ou delay sur une offre gratuite
404Introuvable — application_id ou device_id n’existe pas
429Limite 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.
json
{
  "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
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"
}

La suppression de messages ne libère pas de quota. Vérifiez l’utilisation du jour avec GET /v1/messages/usage.

Documentation de Pocket Alert