API · V1

Programmer vos crons par API

Cron Ping appelle une URL publique à la fréquence choisie. Votre application réalise le traitement et renvoie sa réponse HTTP. Le tableau de bord et l’API partagent les mêmes tâches et les mêmes résultats.

1. Créer une clé API

Ouvrir les clés API. Choisissez l’espace de travail et les droits de lecture ou de gestion. La clé est affichée une seule fois et peut être révoquée. Conservez-la côté serveur ; ne l’incluez pas dans le code public de votre site.

Authorization: Bearer cp_VOTRE_CLE

2. Programmer une tâche

Enregistrez cet exemple dans job.json, puis envoyez-le avec curl.

{
  "name": "Synchroniser les commandes",
  "url": "https://votre-site.fr/api/sync",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"source\":\"cron\"}",
  "scheduleType": "cron",
  "cronExpr": "0 9 * * 1-5",
  "timezone": "Europe/Paris",
  "timeoutSeconds": 10,
  "retries": 0
}

curl -X POST 'https://cron-ping.com/api/v1/jobs' -H "Authorization: Bearer $CRON_PING_API_KEY" -H 'Content-Type: application/json' --data @job.json

HTTP 201 renvoie job.id et nextRunAt. Une fréquence par intervalle utilise scheduleType: period et periodSeconds, par exemple 3600. La tâche est active immédiatement ; paused: true la crée en pause.

3. Lire les tâches et les résultats

curl 'https://cron-ping.com/api/v1/jobs?limit=50' -H "Authorization: Bearer $CRON_PING_API_KEY"

curl 'https://cron-ping.com/api/v1/jobs/JOB_ID' -H "Authorization: Bearer $CRON_PING_API_KEY"

curl 'https://cron-ping.com/api/v1/jobs/JOB_ID/runs?limit=50' -H "Authorization: Bearer $CRON_PING_API_KEY"

curl 'https://cron-ping.com/api/v1/jobs/JOB_ID/runs/RUN_ID' -H "Authorization: Bearer $CRON_PING_API_KEY"

Les listes renvoient nextCursor : transmettez-le dans ?cursor=… pour la page suivante. Les résultats contiennent status, httpStatus, durationMs, attempts, responseBody, truncated, error et les dates. Les valeurs des en-têtes et les instantanés internes ne sont jamais renvoyés.

4. Lancer maintenant

curl -X POST 'https://cron-ping.com/api/v1/jobs/JOB_ID/run' -H "Authorization: Bearer $CRON_PING_API_KEY" -H 'Idempotency-Key: sync-commandes-2026-09-28'

HTTP 202 renvoie run.id et resultUrl. Consultez resultUrl jusqu’au résultat final. Idempotency-Key évite de remettre le même appel en file tant que le résultat est conservé. Un lancement manuel par minute et par tâche, même en pause. Il ne déplace pas l’échéance planifiée.

5. Modifier, suspendre, supprimer

curl -X PATCH 'https://cron-ping.com/api/v1/jobs/JOB_ID' -H "Authorization: Bearer $CRON_PING_API_KEY" -H 'Content-Type: application/json' --data '{"cronExpr":"0 8 * * *"}'

curl -X PATCH 'https://cron-ping.com/api/v1/jobs/JOB_ID' -H "Authorization: Bearer $CRON_PING_API_KEY" -H 'Content-Type: application/json' --data '{"action":"pause"}'

curl -X PATCH 'https://cron-ping.com/api/v1/jobs/JOB_ID' -H "Authorization: Bearer $CRON_PING_API_KEY" -H 'Content-Type: application/json' --data '{"action":"resume"}'

curl -X DELETE 'https://cron-ping.com/api/v1/jobs/JOB_ID' -H "Authorization: Bearer $CRON_PING_API_KEY"

PATCH modifie les champs fournis. headers remplace l’ensemble des en-têtes ; {} les supprime. Une modification ou suppression attend la fin d’un appel en cours (HTTP 409). La pause bloque les futurs passages ; un appel déjà parti peut se terminer.

Monitoring, alertes et reprise

Tout code HTTP 2xx signifie réussite. Les autres codes, erreurs réseau et délais dépassés sont des échecs. États : queued, running, success, failed, interrupted, missed. Les alertes de premier échec puis de rétablissement utilisent vos canaux de notification et partent après épuisement des tentatives.

Les nouvelles tentatives sont désactivées par défaut : jusqu’à deux sur erreur réseau temporaire, HTTP 429 ou 5xx. Toutes portent le même X-Cron-Ping-Run-Id pour permettre à votre application de dédupliquer. Une connexion perdue ne prouve pas que le traitement distant n’a pas eu lieu. Après interruption du worker, un résultat inconnu est marqué interrupted sans rejeu automatique. Une échéance de plus d’une minute manquée est signalée missed, sans rattrapage en rafale.

Reçus d’exécution signés

Les nouveaux résultats HTTP terminés sont signés avec Ed25519. Le reçu inclut les dates, le statut, le code HTTP et une empreinte de l’aperçu de réponse conservé. Il atteste ce que Cron Ping a observé ; il ne prouve pas la réussite du traitement métier distant. Aucun en-tête, corps de requête ou URL secrète n’est inclus.

curl 'https://cron-ping.com/api/v1/jobs/JOB_ID/runs/RUN_ID/receipt' -H "Authorization: Bearer $CRON_PING_API_KEY" -o receipt.json
curl 'https://cron-ping.com/api/v1/receipts/key' -o trusted-key.json
curl 'https://cron-ping.com/verify-receipt.mjs' -o verify-receipt.mjs
node verify-receipt.mjs receipt.json trusted-key.json

Épinglez la clé publique obtenue indépendamment via HTTPS : une clé fournie dans un reçu ne suffit pas à établir la confiance. Conservez cette clé avec votre archive ; lors d’une rotation, les anciens reçus se vérifient avec l’ancienne clé. Modifier un champ invalide la signature. Ces reçus ne sont pas des signatures électroniques qualifiées ni une garantie d’exécution exactement une fois.

Limites

Les nouvelles inscriptions nécessitent une offre Pro ou Business et une carte, avec 14 jours d’essai avant le premier paiement. Les limites de l’offre s’appliquent pendant l’essai. Après expiration, les lancements et modifications renvoient HTTP 402 ; la lecture de l’historique et la suppression restent disponibles selon la rétention.

Surveillance et planification partagent le quota. 120 requêtes API par minute par clé ; 20 clés actives par compte. Corps de requête : 32 Ko. Réponse conservée : 4 Ko. URL publiques HTTP(S) sur ports 80/443 ; adresses privées et réservées refusées, y compris après résolution DNS. Les redirections ne sont pas suivies.

Horaires à la minute, fuseau IANA et changements d’heure pris en compte. Les appels peuvent démarrer quelques secondes après l’échéance selon la charge ; ce service n’est pas un ordonnanceur temps réel.

Codes de réponse

200 / 201 / 202 · 400 données invalides · 401 clé invalide · 402 abonnement requis · 403 droits ou quota · 404 introuvable · 409 exécution en cours · 413 requête trop grande · 429 limite atteinte (Retry-After).

OpenAPI · Programmer un cron · Documentation des pings