REST API

REST API:n avulla voit automatisoida kaiken, minkä voit tehdä hallintapaneelissa: lisätä verkkotunnuksia, käynnistää skannauksia, hakea ja viedä suostumustietueita sekä vastaanottaa webhookeja, kun jokin muuttuu. API on käytettävissä Pro- ja Enterprise-paketeissa.

Todennus

Luo API-avain kohdassa Settings → API keys. Avaimet on rajattu yhteen työtilaan, ja ne ovat joko vain luku- tai luku- ja kirjoitusoikeudellisia. Lähetä avain bearer-tunnisteena:

curl https://api.cookiesh.eu/v1/domains \
  -H "Authorization: Bearer ck_sk_live_..."

Salaiset avaimet alkavat ck_sk_. Älä koskaan käytä niitä selaimessa suoritettavassa koodissa. Script-tagi tarvitsee vain julkisen sivustotunnisteesi.

Kaikki pyynnöt käyttävät HTTPS:ää ja JSONia. Perus-URL on https://api.cookiesh.eu/v1. Aikaleimat ovat ISO 8601 -merkkijonoja UTC-ajassa.

Päätepisteet

Metodi	Polku	Kuvaus
GET	/domains	Listaa työtilan verkkotunnukset
POST	/domains	Lisää verkkotunnus
GET	/domains/{id}	Hae verkkotunnus ja sen asetukset
DELETE	/domains/{id}	Poista verkkotunnus
POST	/domains/{id}/scans	Käynnistä evästeskannaus
GET	/domains/{id}/scans/{scan_id}	Hae skannauksen tila ja tulokset
GET	/domains/{id}/cookies	Listaa luokitellut evästeet ja seurantatyökalut
GET	/consents	Hae suostumustietueita
GET	/consents/{consent_id}	Hae yksi suostumustietue ja sen tiivisteketjutodiste
POST	/exports	Käynnistä suostumustietueiden vienti CSV- tai JSON-muodossa
GET	/exports/{id}	Hae viennin tila ja latausosoite
DELETE	/subjects/{user_id}	Poista kaikki käyttäjätunnisteeseen liitetyt suostumustietueet

Esimerkki: hae yhden kävijän suostumustietueet.

curl "https://api.cookiesh.eu/v1/consents?domain_id=dom_29xk&consent_id=cns_8Hq2Lw" \
  -H "Authorization: Bearer ck_sk_live_..."

{
  "data": [
    {
      "id": "cns_8Hq2Lw",
      "domain_id": "dom_29xk",
      "created_at": "2026-10-12T09:41:07Z",
      "region": "DE",
      "method": "banner",
      "banner_version": "v14",
      "categories": { "necessary": true, "preferences": false, "analytics": true, "marketing": false },
      "hash": "9f2c…e71a"
    }
  ],
  "next_cursor": null
}

Sivutus

Listauspäätepisteet palauttavat enintään 100 kohdetta. Voit pyytää vähemmän limit-parametrilla. Jos tuloksia on enemmän, vastauksessa on next_cursor. Välitä se takaisin cursor-parametrina, niin saat seuraavan sivun. Kursorit ovat voimassa 24 tuntia.

Virheet

Virheissä käytetään tavallisia HTTP-tilakoodeja ja yhtenäistä rungon muotoa:

{
  "error": {
    "type": "invalid_request",
    "message": "domain_id is required",
    "request_id": "req_4Kd92"
  }
}

Tila	Merkitys
400	Pyyntö on virheellinen. Viesti kertoo syyn.
401	API-avain puuttuu tai on virheellinen.
403	Avain on vain luku -oikeudellinen, tai pakettisi ei sisällä tätä ominaisuutta.
404	Resurssia ei ole tässä työtilassa.
429	Pyyntörajoitus ylittyi. Yritä uudelleen Retry-After-otsakkeen ilmoittaman sekuntimäärän kuluttua.
5xx	Meidän päässämme tapahtui virhe. Yritä uudelleen eksponentiaalisesti kasvavin viivein.

Liitä request_id mukaan, kun otat yhteyttä tukeen.

Pyyntörajoitukset

Pro-työtilat voivat tehdä 600 pyyntöä minuutissa ja Enterprise-työtilat 3 000. Jokaisessa vastauksessa on otsakkeet RateLimit-Limit, RateLimit-Remaining ja RateLimit-Reset. Käynnissä olevat viennit eivät kuluta rajaa.

Webhookit

Lisää päätepiste kohdassa Settings → Webhooks ja valitse tapahtumat, jotka haluat vastaanottaa:

Tapahtuma	Lähetetään, kun
consent.created	Kävijä tallentaa uuden valinnan
consent.updated	Kävijä muuttaa aiempaa valintaansa
scan.completed	Evästeskannaus valmistuu
scan.new_items	Skannaus löytää evästeitä tai seurantatyökaluja, jotka on tarkistettava
usage.threshold	Työtila saavuttaa 80 % tai 100 % kuukausittaisista suostumuskirjauksistaan

Jokainen toimitus on POST-pyyntö, jossa on JSON-runko ja Cookiesh-Signature-otsake. Otsakkeessa on aikaleima ja timestamp.body-merkkijonon HMAC-SHA256-allekirjoitus, joka on luotu päätepisteesi allekirjoitusavaimella. Tarkista allekirjoitus ennen kuin luotat sisältöön:

import crypto from 'node:crypto';

export function verify(rawBody: string, header: string, secret: string): boolean {
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // hylkää vanhat toimitukset
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Vastaa 2xx-tilakoodilla 10 sekunnin kuluessa. Epäonnistuneita toimituksia yritetään uudelleen eksponentiaalisesti kasvavin viivein enintään 24 tunnin ajan. Sama tapahtuma voi saapua useammin kuin kerran, joten ohita kaksoiskappaleet tapahtuman id-kentän avulla.