Surveillance

POST /v2/watch transforme n'importe quelle URL en moniteur de changements. Vous enregistrez une page une fois ; un planificateur local au droplet la rend à nouveau selon une cadence fixe dans un véritable Chrome headless, compare chaque capture à la précédente, et vous notifie — par webhook, par e-mail, ou les deux — lorsque la page change réellement. Cela remplace la plomberie de tâche cron, de comparaison de différences et d'alerte que vous devriez sinon mettre en place autour du point d'accès perceive : un seul enregistrement au lieu d'un planificateur, d'un bucket de stockage et d'un script de comparaison.

Voici le plus petit appel utile. Envoyez une URL et récupérez un moniteur programmé pour vérifier toutes les heures :

curl -X POST https://api.enconvert.com/v2/watch \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing"
  }'

La réponse est l'enregistrement complet du moniteur. Il est active immédiatement, et next_check_at est défini au prochain tick du poller :

{
    "watcher_id": "wat_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "url": "https://example.com/pricing",
    "status": "active",
    "frequency_minutes": 60,
    "diff_mode": "auto",
    "track_fields": null,
    "webhook_url": null,
    "notify_email": true,
    "consecutive_errors": 0,
    "checks_count": 0,
    "last_check_at": null,
    "next_check_at": "2026-06-24T18:31:07Z",
    "last_change_at": null,
    "created_at": "2026-06-24T18:31:07Z",
    "updated_at": null
}

À signaler d'emblée. /v2/watch est un point d'accès V2 avec son propre contrôle de plan, distinct des conversions V1. Le nombre de moniteurs actifs que vous pouvez détenir simultanément est plafonné par max_watchers sur votre plan, et un plan où la surveillance est désactivée ne peut pas en créer du tout — les deux refus reviennent en 402. Consultez la page tarifaire pour les allocations actuelles par palier.

Points d'accès

Content-Type : application/json sur POST et PATCH.

Authentification

Authentifiez-vous avec une clé privée dans l'en-tête X-API-Key pour les appels de serveur à serveur. C'est la voie qu'utilise chaque exemple ci-dessous.

X-API-Key: sk_live_your_private_key

Les clés publiques avec un jeton bearer JWT fonctionnent également, selon le même flux que tous les autres points d'accès — générez un jeton avec votre clé pk_, puis envoyez-le comme Authorization: Bearer <token>. Le flux complet, y compris le verrouillage de domaine et le rafraîchissement du jeton, se trouve dans le guide d'authentification.

Chaque clé API porte une liste blanche de points d'accès autorisés. Si /v2/watch n'est pas sur la liste de la clé, la requête de création est rejetée avec 403. Une fois qu'une clé peut créer des moniteurs, elle peut aussi atteindre les routes par moniteur qu'elle possède — GET, PATCH et DELETE sur /v2/watch/{watcher_id} et sa page /snapshots sont autorisés automatiquement, donc vous n'avez pas à mettre chaque verbe sur la liste blanche séparément.

Comment fonctionne la surveillance

Il n'y a aucune file d'attente externe derrière cela — pas de Google Cloud Tasks, pas de planificateur tiers. Le calendrier vit entièrement dans la colonne de base de données next_check_at, et un poller en cours de processus le pilote :

1. Création. Vous faites un POST d'une URL. L'URL est filtrée contre la SSRF (un hôte privé, loopback ou metadata est rejeté avant qu'aucune ligne ne soit écrite), un ID wat_ est généré, et le moniteur est stocké active avec next_check_at défini à maintenant.
2. Réclamation. Un watch_worker local au droplet scanne toutes les 60 secondes à la recherche de lignes actives dont le next_check_at est dépassé. Il les réclame sous FOR UPDATE SKIP LOCKED et avance le calendrier de chacune d'un intervalle complet dans la même transaction — ainsi un rendu lent n'est jamais réclamé deux fois, et un crash en plein rendu saute simplement un cycle.
3. Rendu. Chaque moniteur réclamé est rendu une fois via le singleton Chrome headless partagé — le même pipeline de capture qui sous-tend le point d'accès perceive. Le rendu est sans identifiants : aucune auth, aucun cookie, aucun en-tête n'est stocké, donc rien de secret ne reste au repos pour la vérification récurrente.
4. Notation et diff. Un rendu dont le score est en dessous du seuil de qualité (0.4) ou signalé comme bloqué est enregistré comme une vérification à des fins d'audit uniquement — pas de hash de contenu, donc il ne devient jamais une référence de diff et ne déclenche jamais de notification. Un bon rendu est transformé en capture (texte du contenu principal plus structure extraite), comparé à la dernière bonne capture, et le verdict est écrit dans une ligne de snapshot.
5. Notification. Lorsque le diff signale un changement, le webhook signé HMAC (si défini) et l'e-mail du propriétaire (si notify_email est activé) se déclenchent en parallèle, au mieux.
6. Reprogrammation. Le worker écrit le prochain next_check_at. Trois échecs de rendu consécutifs suspendent le moniteur et envoient un e-mail au propriétaire au lieu de reprogrammer.

Parce que le calendrier est une colonne de base de données, l'indisponibilité ne nécessite aucune logique de récupération : le premier tick après le démarrage ramasse tout ce qui est en retard.

Paramètres de la requête

Création (POST /v2/watch)

Le schéma de la requête est strict (extra="forbid") : un champ inconnu est rejeté avec 422. Il n'y a délibérément aucune surface auth, cookies ou headers ici — les moniteurs restent sans identifiants, la même posture que le point d'accès ingest.

Mise à jour (PATCH /v2/watch/{watcher_id})

Chaque champ est optionnel ; seules les clés présentes dans le corps sont appliquées.

Un corps vide ({}) est rejeté avec 422 plutôt que silencieusement ignoré. Notez que status n'accepte ici que active ou paused — l'état terminal deleted s'atteint via DELETE, jamais PATCH. Reprendre un moniteur suspendu compte comme l'ajout d'un moniteur actif, donc cela revérifie le même plafond max_watchers qu'à la création et peut renvoyer 402.

Modes de diff

diff_mode choisit laquelle des quatre stratégies tenant compte du type de contenu le moteur exécute. auto exécute les quatre et fusionne leurs constatations ; les modes nommés restreignent le diff à une seule stratégie.

Quel que soit le mode que vous choisissez, le similarity du snapshot est toujours le ratio global de la capture entière (0.0–1.0). Sous un mode restreint, cela signifie que similarity peut afficher une valeur basse tandis que has_changes est false — une section que vous ne comparez pas a dérivé, mais rien dans la stratégie que vous avez choisie n'a changé.

Suivre un sous-ensemble de champs

track_fields restreint le diff aux changements dont la section, le champ ou la clé correspond à un terme suivi. Il accepte un objet — ses clés, plus toutes les valeurs de liste, deviennent les termes suivis. Ainsi {"metadata": ["title"]} suit à la fois la section metadata et le champ title. La correspondance se fait par token entier, pas par sous-chaîne : un terme price correspond à offers.price mais pas à priceCurrency.

Réponse

POST, GET /v2/watch/{watcher_id}, PATCH et DELETE renvoient tous le même objet moniteur.

GET /v2/watch renvoie un WatcherSummary compact par ligne (il abandonne diff_mode, track_fields, webhook_url, notify_email et updated_at) enveloppé dans une enveloppe de page :

Historique des snapshots

GET /v2/watch/{watcher_id}/snapshots renvoie la chronologie des vérifications du moniteur, du plus récent au plus ancien. Chaque entrée porte le verdict du diff — le corps de la capture du snapshot lui-même vit dans le stockage et n'est pas renvoyé ici.

À signaler. Les valeurs before et after à l'intérieur de changes sont du contenu de page brut (texte de lien, métadonnées, valeurs JSON-LD), pas une sortie assainie. Si vous les rendez en HTML — un tableau de bord, un e-mail — vous devez les échapper vous-même. Les valeurs de chaîne longues sont déjà tronquées à 2 000 caractères, et un seul diff est plafonné à 500 enregistrements de changement.

Cycle de vie et planification

Un moniteur passe par trois états :

• active — sur le calendrier du poller. next_check_at est défini.
• paused — hors du calendrier (next_check_at est null). Atteint soit par PATCH {"status": "paused"}, soit automatiquement après trois échecs de rendu consécutifs.
• deleted — pierre tombale terminale, atteinte uniquement via DELETE. La ligne est conservée (donc l'historique des vérifications survit) mais elle n'apparaît jamais dans les listes et se lit comme 404 sur les routes par moniteur.

Le plancher horaire est appliqué à deux endroits : à la création/mise à jour, et de nouveau par le planificateur lorsqu'il avance next_check_at. Ainsi même une ligne dont la cadence a été modifiée directement dans la base de données ne peut jamais dépasser le plancher.

Suspension automatique

Après trois échecs de rendu consécutifs, le moniteur est mis à paused, son calendrier est effacé, et — si notify_email est activé — le propriétaire reçoit un e-mail de moniteur suspendu. Une seule vérification réussie remet consecutive_errors à 0. Pour redémarrer un moniteur suspendu, faites un PATCH pour le ramener à active, ce qui réarme next_check_at pour le prochain tick.

Suppression

DELETE /v2/watch/{watcher_id} est une suppression logique : elle bascule status à deleted, efface next_check_at, et renvoie l'enregistrement mis en pierre tombale avec un 200. Elle est idempotente — supprimer un moniteur déjà supprimé renvoie le même enregistrement inchangé. Les moniteurs supprimés cessent immédiatement de compter dans votre plafond max_watchers (seuls les moniteurs active comptent).

Exemples de code

curl — créer avec les valeurs par défaut

curl -X POST https://api.enconvert.com/v2/watch \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing"
  }'

curl — toutes les 6 heures, webhook + suivi de tableaux

curl -X POST https://api.enconvert.com/v2/watch \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "frequency_minutes": 360,
    "diff_mode": "tables",
    "webhook_url": "https://hooks.example.com/enconvert",
    "notify_email": false
  }'

curl — suspendre, puis reprendre

curl -X PATCH \
  https://api.enconvert.com/v2/watch/wat_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

curl -X PATCH \
  https://api.enconvert.com/v2/watch/wat_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Python

import requests

BASE = "https://api.enconvert.com"
HEADERS = {"X-API-Key": "sk_live_your_private_key"}

# Create a watcher.
created = requests.post(
    f"{BASE}/v2/watch",
    headers=HEADERS,
    json={
        "url": "https://example.com/pricing",
        "frequency_minutes": 120,
        "diff_mode": "auto",
    },
)
created.raise_for_status()
watcher = created.json()
watcher_id = watcher["watcher_id"]

# Later: pull the check history and read the diff verdicts.
snaps = requests.get(
    f"{BASE}/v2/watch/{watcher_id}/snapshots",
    headers=HEADERS,
)
snaps.raise_for_status()
for snap in snaps.json()["snapshots"]:
    if snap["has_changes"]:
        print(snap["checked_at"], snap["change_count"], snap["similarity"])

Node.js

const BASE = "https://api.enconvert.com";
const HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "sk_live_your_private_key"
};

// Create a watcher.
const created = await fetch(`${BASE}/v2/watch`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({
        url: "https://example.com/pricing",
        frequency_minutes: 120,
        diff_mode: "auto"
    })
});
const watcher = await created.json();

// List this project's watchers, newest first.
const list = await fetch(`${BASE}/v2/watch?limit=20`, {
    headers: { "X-API-Key": "sk_live_your_private_key" }
}).then(r => r.json());

console.log(watcher.watcher_id, list.has_more);

Contrôle de plan

La surveillance est contrôlée de deux façons, toutes deux distinctes de votre quota de conversions V1 :

• watch_enabled — un drapeau booléen de plan. Un plan sans ce drapeau ne peut pas créer de moniteur du tout (402).
• max_watchers — le plafond du nombre de moniteurs active qu'un projet peut détenir simultanément. Les moniteurs suspendus et supprimés ne comptent pas. Une valeur de 0 avec le drapeau activé signifie illimité (entreprise/admin).

Créer un moniteur ne consomme pas une conversion ni une opération V2 — la surveillance est contrôlée par le nombre de moniteurs que vous détenez, pas par un compteur par appel. Parce que chaque moniteur vérifie selon une cadence horaire ou plus lente, le volume total de vérifications d'un projet est borné par max_watchers et le plancher horaire ensemble. Les allocations actuelles de max_watchers par plan se trouvent sur la page tarifaire.

Réponses d'erreur

La référence complète des codes de statut se trouve dans le guide des codes d'erreur.

Limites