API-referenssi

Pieni, vakaa REST API monitorien ja kanavien hallintaan sekä muutosten kyselyyn. Sama pinta-ala kuin hallintapaneelilla.

Perus-URL

Tuotanto: https://api.pagedeltas.com. Kaikkien päätepisteiden etuliitteenä on /api. Onnistuneet vastaukset ovat JSON-muodossa.

Todennus

Luo avain kohdasta Asetukset → API-avaimet (edellyttää muokkaaja- tai ylläpitäjäroolia). Avain näytetään vain kerran luonnin yhteydessä — kopioi se välittömästi. Peruuttaaksesi avaimen, poista se samalta sivulta.

Authorization: Bearer pdt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Avaimet on rajoitettu ne luoneeseen organisaatioon ja ne toimivat ylläpitäjätason käyttöoikeuksilla kyseisessä organisaatiossa, riippumatta käyttäjästä. Niitä ei ole sidottu jäseneen, joten tiimikaverin poistaminen ei peruuta organisaation avaimia — poista itse avain katkaistaksesi pääsyn.

Virheet

Virheet palauttavat muun kuin 2xx-tilan. Todennus- ja käyttöoikeusvirheet tulevat takaisin lyhyenä pelkkänä tekstiviestinä (esim. unauthorized, forbidden); kiintiö- ja nopeusrajoitusvirheet palauttavat pienen JSON-rungon, jossa on viesti ja asiaankuuluvat numerot. Älä jäsennä kiinteää virhekuorta — haaraudu HTTP-tilakoodin perusteella:

400 — virheellinen pyyntö (huono JSON, virheellinen URL, puuttuva kenttä).
401 — puuttuvat tai virheelliset tunnistetiedot.
403 — todennettu, mutta roolillasi ei ole lupaa tähän toimintoon.
404 — resurssi puuttuu tai ei ole organisaatiossasi.
409 — ristiriita (esim. monitori on keskeytetty toistuvien estojen vuoksi).
422 — kiintiö ylittyisi (esim. suunnitelmasi monitoriraja). JSON-runko sisältää current ja limit.
429 — nopeusrajoitettu (manuaaliset tarkistukset). Peruuta ja yritä uudelleen Retry-After -viiveen jälkeen.

Esimerkki kiintiövirheestä (422):

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

Päätepisteiden viite

Metodi & polku	Kuvaus
`GET /api/monitors`	Listaa organisaatiosi monitorit.
`POST /api/monitors`	Luo yksittäinen monitori.
`GET /api/monitors/{id}`	Hae yksittäinen monitori.
`PATCH /api/monitors/{id}`	Päivitä `url`, `nl_description`, `filter_prompt`, `css_selector`, `xpath_selector`, `status`.
`DELETE /api/monitors/{id}`	Poista monitori ja sen historia.
`POST /api/monitors/{id}/check-now`	Aseta jonoon välitön tarkistus, ohittaen aikataulun (nopeusrajoitettu, katso alla).
`GET /api/monitors/{id}/changes`	Listaa havaitut muutokset monitorille (tukee `?limit=`, max 100).
`POST /api/monitors/import`	Massatuonti moniosaisen CSV-latauksen kautta (`file`-kenttä).
`POST /api/monitors/bulk-pause`, `bulk-resume`, `bulk-delete`	Käytä toimintoa luetteloon monitoritunnuksista.
`GET\|PUT /api/monitors/{id}/alert-channels`	Lue tai korvaa monitorin kanavien ohitukset.
`GET /api/alert-channels`	Listaa ilmoituskanavat.
`POST /api/alert-channels`	Luo kanava.
`PATCH\|DELETE /api/alert-channels/{id}`	Päivitä tai poista kanava.
`POST /api/alert-channels/{id}/test`	Lähetä testikuorma toimituksen varmistamiseksi.
`GET\|POST /api/sitemap-monitors`	Listaa tai luo sitemap-monitoreita.
`POST /api/sitemap-monitors/import`	Massaluo sitemap-monitoreita moniosaisen CSV-latauksen kautta (`file`-kenttä).
`GET\|POST\|DELETE /api/tokens`	Listaa, luo ja poista API-avaimia.
`GET /api/billing/plan`	Organisaatiosi nykyinen suunnitelma ja rajat.
`GET /api/plans`	Julkinen — listaa saatavilla olevat suunnitelmat (ei vaadi todennusta).

Esimerkki — luo monitori

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

Valinnaiset kentät: filter_prompt, css_selector, xpath_selector, is_pdf ja channel_ids (monitorikohtaiset kanavaohitukset; jätä pois käyttääksesi organisaation oletuksia). Ei ole frequency-kenttää — aikataulutus on mukautuva.

Esimerkki — kysy muutoksia

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

Palauttaa viimeisimmät muutokset ensin (oletus 50, max 100). Ei ole osoitinta — sivuta säätämällä limit-arvoa ja seuraamalla viimeisintä detected_at-arvoa, jonka olet jo nähnyt.

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

Nopeusrajoitukset

Luku- ja kirjoituspäätepisteissä ei ole tällä hetkellä avainkohtaisia nopeusrajoituksia. Ainoa poikkeus on manuaaliset tarkistukset:

Check-now: 1 pyyntö / minuutti / monitori.

Kun osut tähän rajaan, vastaus on 429 ja Retry-After-otsikko sekunneissa. Rajoita edelleen tahtiasi järkevästi muissa päätepisteissä.

Versiointi

Pyrimme pitämään tämän pinnan vakaana. Uusia kenttiä ja päätepisteitä saatetaan lisätä ilman erillistä ilmoitusta, joten kirjoita asiakkaita, jotka sivuuttavat tuntemattomat JSON-kentät.