REST-API

Mit der REST-API automatisieren Sie alles, was Sie auch im Dashboard tun können: Domains hinzufügen, Scans starten, Einwilligungsnachweise durchsuchen und exportieren und Webhooks empfangen, wenn sich etwas ändert. Sie ist in den Tarifen Pro und Enterprise verfügbar.

Authentifizierung

Erstellen Sie unter Settings → API keys einen API-Schlüssel. Schlüssel gelten jeweils für einen Workspace und sind entweder schreibgeschützt oder haben Lese- und Schreibzugriff. Senden Sie den Schlüssel als Bearer-Token:

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

Geheime Schlüssel beginnen mit ck_sk_. Verwenden Sie sie niemals in Browser-Code. Das Script-Tag braucht nur Ihre öffentliche Site ID.

Alle Anfragen verwenden HTTPS und JSON. Die Basis-URL lautet https://api.cookiesh.eu/v1. Zeitstempel sind ISO-8601-Strings in UTC.

Endpunkte

Methode	Pfad	Beschreibung
GET	/domains	Domains im Workspace auflisten
POST	/domains	Domain hinzufügen
GET	/domains/{id}	Domain mit ihren Einstellungen abrufen
DELETE	/domains/{id}	Domain entfernen
POST	/domains/{id}/scans	Cookie-Scan starten
GET	/domains/{id}/scans/{scan_id}	Status und Ergebnisse eines Scans abrufen
GET	/domains/{id}/cookies	Klassifizierte Cookies und Tracker auflisten
GET	/consents	Einwilligungsnachweise durchsuchen
GET	/consents/{consent_id}	Einzelnen Einwilligungsnachweis mit Hash-Ketten-Nachweis abrufen
POST	/exports	CSV- oder JSON-Export von Einwilligungsnachweisen starten
GET	/exports/{id}	Status und Download-URL eines Exports abrufen
DELETE	/subjects/{user_id}	Alle mit einer Nutzer-ID verknüpften Einwilligungsnachweise löschen

Beispiel: die Einwilligungsnachweise eines Besuchers finden.

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
}

Paginierung

Listen-Endpunkte geben bis zu 100 Einträge zurück. Mit limit fordern Sie weniger an. Gibt es weitere Ergebnisse, enthält die Antwort einen next_cursor. Übergeben Sie ihn als cursor, um die nächste Seite abzurufen. Cursor bleiben 24 Stunden gültig.

Fehler

Fehler verwenden die üblichen HTTP-Statuscodes und einen einheitlichen Body:

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

Status	Bedeutung
400	Die Anfrage ist ungültig. Die Meldung erklärt, warum.
401	Der API-Schlüssel fehlt oder ist ungültig.
403	Der Schlüssel ist schreibgeschützt, oder Ihr Tarif enthält diese Funktion nicht.
404	Die Ressource existiert in diesem Workspace nicht.
429	Sie haben das Rate Limit erreicht. Versuchen Sie es nach der in Retry-After angegebenen Anzahl Sekunden erneut.
5xx	Auf unserer Seite ist etwas schiefgelaufen. Wiederholen Sie die Anfrage mit exponentiellem Backoff.

Geben Sie die request_id an, wenn Sie den Support kontaktieren.

Rate Limits

Pro-Workspaces können 600 Anfragen pro Minute stellen, Enterprise-Workspaces 3.000. Jede Antwort enthält die Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset. Laufende Exporte zählen nicht gegen das Limit.

Webhooks

Fügen Sie unter Settings → Webhooks einen Endpunkt hinzu und wählen Sie die Ereignisse, die Sie empfangen möchten:

Ereignis	Wird gesendet, wenn
consent.created	ein Besucher eine neue Entscheidung speichert
consent.updated	ein Besucher eine frühere Entscheidung ändert
scan.completed	ein Cookie-Scan abgeschlossen ist
scan.new_items	ein Scan Cookies oder Tracker findet, die geprüft werden müssen
usage.threshold	der Workspace 80 % oder 100 % seiner monatlichen Consent-Logs erreicht

Jede Zustellung ist ein POST mit JSON-Body und einem Header Cookiesh-Signature. Der Header enthält einen Zeitstempel und eine HMAC-SHA256-Signatur von timestamp.body, erstellt mit dem Signing Secret Ihres Endpunkts. Prüfen Sie sie, bevor Sie dem Payload vertrauen:

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; // alte Zustellungen ablehnen
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status. Fehlgeschlagene Zustellungen werden bis zu 24 Stunden lang mit exponentiellem Backoff wiederholt. Ereignisse können mehrfach ankommen. Nutzen Sie daher die id des Ereignisses, um Duplikate zu ignorieren.