Référence API

Une API REST réduite et stable pour gérer surveillances et canaux et interroger les changements. Même périmètre que le tableau de bord.

URL de base

Production : https://api.pagedeltas.com. Tous les endpoints sont préfixés par /api. Les réponses réussies sont en JSON.

Authentification

Créez une clé depuis Settings → API keys (rôle éditeur ou administrateur requis). La clé n'est affichée qu'une seule fois à sa création — copiez-la immédiatement. Pour révoquer une clé, supprimez-la depuis la même page.

Authorization: Bearer pdt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Les clés sont rattachées à l'organisation qui les a créées et agissent avec un accès de niveau administrateur au sein de cette organisation, indépendamment de tout utilisateur. Elles ne sont pas liées à un membre, donc retirer un coéquipier ne révoque pas les clés de l'organisation — supprimez la clé elle-même pour couper l'accès.

Erreurs

Les erreurs renvoient un statut non-2xx. Les erreurs d'authentification et de permission reviennent sous forme d'un court message en texte brut (par ex. unauthorized, forbidden) ; les erreurs de quota et de limitation de débit renvoient un petit corps JSON avec un message et les nombres pertinents. N'analysez pas une enveloppe d'erreur figée — branchez selon le code de statut HTTP :

400 — requête mal formée (JSON invalide, URL invalide, champ manquant).
401 — identifiants manquants ou invalides.
403 — authentifié, mais votre rôle n'a pas la permission pour cette action.
404 — ressource absente ou hors de votre organisation.
409 — conflit (par ex. la surveillance est en pause à cause de blocages répétés).
422 — un quota serait dépassé (par ex. la limite de surveillances de votre offre). Le corps JSON inclut current et limit.
429 — débit limité (vérifications manuelles). Patientez et réessayez après le délai indiqué dans Retry-After.

Exemple d'erreur de quota (422) :

{
  "error": "plan_url_limit exceeded",
  "current": 100,
  "limit": 100,
  "message": "Creating this monitor would exceed your plan's monitor limit (100)."
}

Référence des endpoints

Méthode et chemin	Description
`GET /api/monitors`	Lister les surveillances de votre organisation.
`POST /api/monitors`	Créer une seule surveillance.
`GET /api/monitors/{id}`	Obtenir une seule surveillance.
`PATCH /api/monitors/{id}`	Mettre à jour `url`, `nl_description`, `filter_prompt`, `css_selector`, `xpath_selector`, `status`.
`DELETE /api/monitors/{id}`	Supprimer une surveillance et son historique.
`POST /api/monitors/{id}/check-now`	Mettre en file une vérification immédiate, en contournant la planification (débit limité, voir ci-dessous).
`GET /api/monitors/{id}/changes`	Lister les changements détectés pour une surveillance (prend en charge `?limit=`, max 100).
`POST /api/monitors/import`	Import en masse via téléversement CSV multipart (champ `file`).
`POST /api/monitors/bulk-pause`, `bulk-resume`, `bulk-delete`	Appliquer une action à une liste d'identifiants de surveillances.
`GET\|PUT /api/monitors/{id}/alert-channels`	Lire ou remplacer les surcharges de canaux d'une surveillance.
`GET /api/alert-channels`	Lister les canaux de notification.
`POST /api/alert-channels`	Créer un canal.
`PATCH\|DELETE /api/alert-channels/{id}`	Mettre à jour ou supprimer un canal.
`POST /api/alert-channels/{id}/test`	Envoyer une charge utile de test pour vérifier la distribution.
`GET\|POST /api/sitemap-monitors`	Lister ou créer des surveillances de sitemap.
`POST /api/sitemap-monitors/import`	Créer en masse des surveillances de sitemap via téléversement CSV multipart (champ `file`).
`GET\|POST\|DELETE /api/tokens`	Lister, créer et supprimer des clés API.
`GET /api/billing/plan`	L'offre et les limites actuelles de votre organisation.
`GET /api/plans`	Public — lister les offres disponibles (aucune authentification requise).

Exemple — créer une surveillance

curl -X POST https://api.pagedeltas.com/api/monitors \
  -H "Authorization: Bearer $PAGEDELTAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "nl_description": "Competitor pricing; alert on plan or price changes",
    "filter_prompt": "Alert on plan or price changes; ignore copy tweaks",
    "channel_ids": []
  }'

Champs facultatifs : filter_prompt, css_selector, xpath_selector, is_pdf et channel_ids (surcharges de canaux par surveillance ; omettez pour utiliser les valeurs par défaut de l'organisation). Il n'y a pas de frequency — la planification est adaptative.

Exemple — interroger les changements

GET /api/monitors/01HW2X.../changes?limit=50
Authorization: Bearer $PAGEDELTAS_TOKEN

Renvoie d'abord les changements les plus récents (50 par défaut, 100 max). Il n'y a pas de curseur — paginez en ajustant limit et en suivant le dernier detected_at que vous avez déjà vu.

{
  "changes": [
    {
      "id": "01HW3...",
      "detected_at": "2026-06-01T08:42:00Z",
      "summary": "Pro plan increased from $29 to $39/month."
    }
  ]
}

Limites de débit

Il n'y a actuellement aucune limite de débit par clé sur les endpoints de lecture et d'écriture. La seule exception concerne les vérifications manuelles :

Check-now : 1 requête / minute / surveillance.

Lorsque vous atteignez cette limite, la réponse est 429 avec un en-tête Retry-After en secondes. Limitez-vous tout de même raisonnablement sur les autres endpoints.

Versionnage

Nous visons à garder ce périmètre stable. De nouveaux champs et endpoints peuvent être ajoutés sans préavis, alors écrivez des clients qui ignorent les champs JSON inconnus.