Riferimento API

Una piccola e stabile API REST per gestire monitor e canali e interrogare i cambiamenti. Stessa area di copertura della dashboard.

URL di base

Produzione: https://api.pagedeltas.com. Tutti gli endpoint hanno il prefisso /api. Le risposte andate a buon fine sono in formato JSON.

Autenticazione

Crea una chiave da Impostazioni → Chiavi API (è richiesto il ruolo editor o admin). La chiave viene mostrata una sola volta al momento della creazione: copiala immediatamente. Per revocare una chiave, eliminala dalla stessa pagina.

Authorization: Bearer pdt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Le chiavi sono limitate all'organizzazione che le ha create e agiscono con accesso a livello di amministratore all'interno di quell'organizzazione, indipendentemente da qualsiasi utente. Non sono legate a un membro, quindi la rimozione di un compagno di squadra non revoca le chiavi dell'organizzazione — elimina la chiave stessa per interrompere l'accesso.

Errori

Gli errori restituiscono uno stato diverso da 2xx. Gli errori di autenticazione e permesso vengono restituiti come un breve messaggio in testo semplice (es. unauthorized, forbidden); gli errori di quota e limite di velocità restituiscono un piccolo corpo JSON con un messaggio e i numeri rilevanti. Non analizzare un involucro di errore fisso — dirama in base al codice di stato HTTP:

400 — richiesta malformata (JSON non valido, URL non valido, campo mancante).
401 — credenziali mancanti o non valide.
403 — autenticato ma il tuo ruolo non ha il permesso per questa azione.
404 — risorsa mancante o non presente nella tua organizzazione.
409 — conflitto (es. il monitor è in pausa a causa di blocchi ripetuti).
422 — una quota verrebbe superata (es. il limite di monitor del tuo piano). Il corpo JSON include current e limit.
429 — limite di velocità raggiunto (controlli manuali). Attendi e riprova dopo il ritardo indicato in Retry-After.

Esempio di errore di quota (422):

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

Riferimento endpoint

Metodo e percorso	Descrizione
`GET /api/monitors`	Elenca i monitor nella tua organizzazione.
`POST /api/monitors`	Crea un singolo monitor.
`GET /api/monitors/{id}`	Ottieni un singolo monitor.
`PATCH /api/monitors/{id}`	Aggiorna `url`, `nl_description`, `filter_prompt`, `css_selector`, `xpath_selector`, `status`.
`DELETE /api/monitors/{id}`	Elimina un monitor e la sua cronologia.
`POST /api/monitors/{id}/check-now`	Accoda un controllo immediato, ignorando la pianificazione (limite di velocità applicato, vedi sotto).
`GET /api/monitors/{id}/changes`	Elenca i cambiamenti rilevati per un monitor (supporta `?limit=`, max 100).
`POST /api/monitors/import`	Importazione di massa tramite caricamento CSV multipart (campo `file`).
`POST /api/monitors/bulk-pause`, `bulk-resume`, `bulk-delete`	Applica un'azione a un elenco di ID monitor.
`GET\|PUT /api/monitors/{id}/alert-channels`	Leggi o sostituisci gli override dei canali di un monitor.
`GET /api/alert-channels`	Elenca i canali di notifica.
`POST /api/alert-channels`	Crea un canale.
`PATCH\|DELETE /api/alert-channels/{id}`	Aggiorna o elimina un canale.
`POST /api/alert-channels/{id}/test`	Invia un payload di test per verificare la consegna.
`GET\|POST /api/sitemap-monitors`	Elenca o crea monitor di sitemap.
`POST /api/sitemap-monitors/import`	Creazione di massa di monitor di sitemap tramite caricamento CSV multipart (campo `file`).
`GET\|POST\|DELETE /api/tokens`	Elenca, crea ed elimina chiavi API.
`GET /api/billing/plan`	Piano attuale e limiti della tua organizzazione.
`GET /api/plans`	Pubblico — elenca i piani disponibili (non richiede autenticazione).

Esempio — creare un monitor

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": []
  }'

Campi opzionali: filter_prompt, css_selector, xpath_selector, is_pdf e channel_ids (override dei canali per monitor; omettere per usare i predefiniti dell'organizzazione). Non esiste frequency — la pianificazione è adattiva.

Esempio — interrogare i cambiamenti

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

Restituisce prima i cambiamenti più recenti (predefinito 50, max 100). Non esiste un cursore — pagina regolando limit e tracciando l'ultimo detected_at che hai già visto.

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

Limiti di velocità

Al momento non ci sono limiti di velocità per chiave sugli endpoint di lettura e scrittura. L'unica eccezione sono i controlli manuali:

Check-now: 1 richiesta / minuto / monitor.

Quando raggiungi tale limite, la risposta è 429 con un header Retry-After in secondi. Ti preghiamo comunque di limitarti ragionevolmente sugli altri endpoint.

Versioning

Miriamo a mantenere stabile questa interfaccia. Nuovi campi ed endpoint possono essere aggiunti senza preavviso, quindi scrivi client che ignorano i campi JSON sconosciuti.