Watch

POST /v2/watch trasforma qualsiasi URL in un monitor delle modifiche. Registri una pagina una volta sola; uno scheduler locale al droplet la ri-renderizza a cadenza fissa in Chrome headless reale, confronta ogni cattura con quella precedente e ti avvisa — via webhook, email o entrambi — quando la pagina cambia davvero. Sostituisce l'impalcatura di cron job più diffing più alerting che altrimenti dovresti costruire attorno all'endpoint perceive: un record invece di uno scheduler, un bucket di storage e uno script di confronto.

Ecco la chiamata utile più piccola. Invii un URL e ottieni un watcher pianificato per controllare ogni ora:

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 risposta è il record completo del watcher. È active immediatamente, e next_check_at è impostato sul prossimo tick del 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
}

Da segnalare subito. /v2/watch è un endpoint V2 con un proprio gate di piano, separato dalle conversioni V1. Quanti watcher attivi puoi mantenere contemporaneamente è limitato da max_watchers sul tuo piano, e un piano con watch disabilitato non può crearne nessuno — entrambe le negazioni tornano come 402. Vedi la pagina dei prezzi per le allocazioni correnti per tier.

Endpoints

Content-Type: application/json su POST e PATCH.

Authentication

Autenticati con una chiave privata nell'header X-API-Key per le chiamate server-to-server. Questo è il percorso usato da ogni esempio qui sotto.

X-API-Key: sk_live_your_private_key

Funzionano anche le chiavi pubbliche con un token bearer JWT, usando lo stesso flusso di ogni altro endpoint — genera un token con la tua chiave pk_, poi invialo come Authorization: Bearer <token>. Il flusso completo, incluso il domain locking e il refresh del token, è nella guida all'autenticazione.

Ogni chiave API porta con sé un'allowlist di endpoint consentiti. Se /v2/watch non è nella lista della chiave, la richiesta di creazione viene rifiutata con 403. Una volta che una chiave può creare watcher, può anche raggiungere le route per-watcher che possiede — GET, PATCH e DELETE su /v2/watch/{watcher_id} e la sua pagina /snapshots sono consentiti automaticamente, quindi non devi inserire ogni verbo separatamente nell'allowlist.

How watch works

Non c'è nessuna coda esterna dietro a questo — niente Google Cloud Tasks, nessuno scheduler di terze parti. Lo schedule risiede interamente nella colonna del database next_check_at, e un poller in-process lo guida:

1. Create. Fai POST di un URL. L'URL viene sottoposto a screening SSRF (un host privato, loopback o di metadata viene rifiutato prima che venga scritta qualsiasi riga), un ID wat_ viene coniato, e il watcher viene memorizzato come active con next_check_at impostato su adesso.
2. Claim. Un watch_worker locale al droplet effettua una scansione ogni 60 secondi per le righe attive il cui next_check_at è passato. Le rivendica sotto FOR UPDATE SKIP LOCKED e fa avanzare lo schedule di ciascuna di un intero intervallo nella stessa transazione — così un render lento non viene mai rivendicato due volte, e un crash a metà render salta semplicemente un ciclo.
3. Render. Ogni watcher rivendicato viene renderizzato una volta attraverso il singleton condiviso di Chrome headless — la stessa pipeline di cattura dietro l'endpoint perceive. Il render è credential-free: nessuna auth, cookie o header viene memorizzato, quindi nulla di segreto resta a riposo per il controllo ricorrente.
4. Score and diff. Un render con punteggio sotto la soglia minima di qualità (0.4) o contrassegnato come bloccato viene registrato come un controllo di solo audit — nessun content hash, quindi non diventa mai una baseline di diff e non scatena mai una notifica. Un buon render viene trasformato in una cattura (testo del contenuto principale più struttura estratta), confrontato con l'ultima cattura buona, e il verdetto viene scritto in una riga di snapshot.
5. Notify. Quando il diff segnala una modifica, il webhook firmato con HMAC (se impostato) e l'email del proprietario (se notify_email è attivo) partono in modo concorrente, best-effort.
6. Reschedule. Il worker scrive il prossimo next_check_at. Tre render falliti consecutivi mettono in pausa il watcher e inviano un'email al proprietario invece di rischedulare.

Poiché lo schedule è una colonna del database, il downtime non necessita di logica di recupero: il primo tick dopo il boot raccoglie tutto ciò che è in ritardo.

Request parameters

Create (POST /v2/watch)

Lo schema della richiesta è rigido (extra="forbid"): un campo sconosciuto viene rifiutato con 422. Deliberatamente non c'è qui alcuna superficie auth, cookies o headers — i watcher restano credential-free, la stessa postura di l'endpoint ingest.

Update (PATCH /v2/watch/{watcher_id})

Ogni campo è opzionale; vengono applicate solo le chiavi presenti nel body.

Un body vuoto ({}) viene rifiutato con 422 invece di essere silenziosamente trattato come no-op. Nota che status qui accetta solo active o paused — lo stato terminale deleted si raggiunge tramite DELETE, mai con PATCH. Riprendere un watcher in pausa conta come aggiungere un monitor attivo, quindi ricontrolla lo stesso cap max_watchers della creazione e può restituire 402.

Diff modes

diff_mode seleziona quale delle quattro strategie content-type-aware esegue il motore. auto esegue tutte e quattro e unisce i loro risultati; le modalità nominate restringono il diff a una singola strategia.

Qualunque modalità tu scelga, la similarity dello snapshot è sempre il rapporto complessivo sull'intera cattura (0.0–1.0). In una modalità ristretta questo significa che similarity può risultare bassa mentre has_changes è false — una sezione che non stai confrontando è cambiata, ma nulla nella strategia scelta è cambiato.

Tracking a subset of fields

track_fields restringe il diff alle modifiche la cui sezione, campo o chiave corrisponde a un termine tracciato. Accetta un oggetto — le sue chiavi, più qualsiasi valore di lista, diventano i termini tracciati. Quindi {"metadata": ["title"]} traccia sia la sezione metadata sia il campo title. Il matching è su token interi, non su sottostringa: un termine price corrisponde a offers.price ma non a priceCurrency.

Response

POST, GET /v2/watch/{watcher_id}, PATCH e DELETE restituiscono tutti lo stesso oggetto watcher.

GET /v2/watch restituisce un WatcherSummary compatto per riga (omette diff_mode, track_fields, webhook_url, notify_email e updated_at) avvolto in una busta di paginazione:

Snapshot history

GET /v2/watch/{watcher_id}/snapshots restituisce la timeline dei controlli del watcher, dal più recente. Ogni voce porta con sé il verdetto del diff — il corpo della cattura dello snapshot stesso risiede nello storage e non viene restituito qui.

Da segnalare. I valori before e after all'interno di changes sono contenuto grezzo della pagina (testo dei link, metadata, valori JSON-LD), non output sanitizzato. Se li renderizzi in HTML — una dashboard, un'email — devi effettuare tu stesso l'escape. I valori di stringa lunghi sono già troncati a 2.000 caratteri, e un singolo diff è limitato a 500 record di modifica.

Lifecycle and scheduling

Un watcher attraversa tre stati:

• active — sullo schedule del poller. next_check_at è impostato.
• paused — fuori dallo schedule (next_check_at è null). Raggiunto o tramite PATCH {"status": "paused"} o automaticamente dopo tre render falliti consecutivi.
• deleted — tombstone terminale, raggiunto solo tramite DELETE. La riga viene conservata (così la cronologia dei controlli sopravvive) ma non compare mai negli elenchi e si legge come 404 sulle route per-watcher.

La soglia minima oraria è applicata in due punti: alla creazione/aggiornamento, e di nuovo dallo scheduler quando fa avanzare next_check_at. Così anche una riga la cui cadenza è stata modificata direttamente nel database non può mai superare la soglia minima.

Auto-pause

Dopo tre render falliti consecutivi, il watcher viene impostato su paused, il suo schedule viene azzerato, e — se notify_email è attivo — il proprietario riceve un'email di watcher in pausa. Un singolo controllo riuscito riporta consecutive_errors a 0. Per riavviare un watcher in pausa, fai PATCH riportandolo ad active, il che riarma next_check_at per il prossimo tick.

Deletion

DELETE /v2/watch/{watcher_id} è un soft-delete: capovolge status a deleted, azzera next_check_at, e restituisce il record con tombstone con un 200. È idempotente — eliminare un watcher già eliminato restituisce lo stesso record invariato. I watcher eliminati smettono di contare contro il tuo cap max_watchers immediatamente (contano solo i watcher active).

Code examples

curl — create with defaults

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 — every-6-hours, webhook + table tracking

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 — pause, then resume

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

Plan gating

Watch è gated in due modi, entrambi separati dalla tua quota di conversioni V1:

• watch_enabled — un flag booleano di piano. Un piano senza di esso non può creare affatto un watcher (402).
• max_watchers — il cap su quanti watcher active un progetto può mantenere contemporaneamente. I watcher in pausa ed eliminati non contano. Un valore di 0 con il flag attivo significa illimitato (enterprise/admin).

Creare un watcher non consuma una conversione o un'operazione V2 — watch è gated da quanti watcher mantieni, non da un contatore per chiamata. Poiché ogni watcher controlla a cadenza oraria-o-più-lenta, il volume totale di controlli di un progetto è limitato congiuntamente da max_watchers e dalla soglia minima oraria. Le allocazioni correnti di max_watchers per piano risiedono su la pagina dei prezzi.

Error responses

Il riferimento completo dei codici di stato è nella guida ai codici di errore.

Limits