API REST

L’API REST vous permet d’automatiser tout ce que vous faites dans le tableau de bord : ajouter des domaines, lancer des scans, rechercher et exporter des enregistrements de consentement, et recevoir des webhooks lorsque quelque chose change. Elle est disponible avec les offres Pro et Enterprise.

Authentification

Créez une clé d’API sous Settings → API keys. Chaque clé est limitée à un espace de travail et donne un accès en lecture seule ou en lecture-écriture. Envoyez la clé sous forme de jeton bearer :

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

Les clés secrètes commencent par ck_sk_. Ne les utilisez jamais dans du code exécuté par le navigateur. La balise script n’a besoin que de votre Site ID public.

Toutes les requêtes utilisent HTTPS et JSON. L’URL de base est https://api.cookiesh.eu/v1. Les horodatages sont des chaînes ISO 8601 en UTC.

Points de terminaison

Méthode	Chemin	Description
GET	/domains	Lister les domaines de l’espace de travail
POST	/domains	Ajouter un domaine
GET	/domains/{id}	Obtenir un domaine et ses paramètres
DELETE	/domains/{id}	Supprimer un domaine
POST	/domains/{id}/scans	Lancer un scan des cookies
GET	/domains/{id}/scans/{scan_id}	Obtenir le statut et les résultats d’un scan
GET	/domains/{id}/cookies	Lister les cookies et traceurs classés
GET	/consents	Rechercher des enregistrements de consentement
GET	/consents/{consent_id}	Obtenir un enregistrement de consentement avec sa preuve de chaînage par hachage
POST	/exports	Lancer un export CSV ou JSON des enregistrements de consentement
GET	/exports/{id}	Obtenir le statut d’un export et son URL de téléchargement
DELETE	/subjects/{user_id}	Supprimer tous les enregistrements de consentement liés à un identifiant utilisateur

Exemple : retrouver les enregistrements de consentement d’un visiteur.

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
}

Pagination

Les points de terminaison de liste renvoient jusqu’à 100 éléments. Indiquez limit pour en demander moins. S’il reste des résultats, la réponse contient un next_cursor. Renvoyez-le dans cursor pour obtenir la page suivante. Les curseurs restent valables 24 heures.

Erreurs

Les erreurs utilisent les codes de statut HTTP standard et un corps de réponse uniforme :

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

Statut	Signification
400	La requête n’est pas valide. Le message en indique la raison.
401	La clé d’API est absente ou non valide.
403	La clé est en lecture seule, ou votre offre n’inclut pas cette fonctionnalité.
404	La ressource n’existe pas dans cet espace de travail.
429	Vous avez atteint la limite de requêtes. Réessayez après le nombre de secondes indiqué dans Retry-After.
5xx	Une erreur s’est produite de notre côté. Réessayez avec un délai exponentiel.

Indiquez le request_id lorsque vous contactez le support.

Limites de requêtes

Les espaces de travail Pro peuvent effectuer 600 requêtes par minute, et les espaces de travail Enterprise 3 000. Chaque réponse inclut les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset. Les exports en cours ne sont pas décomptés de la limite.

Webhooks

Ajoutez un point de terminaison sous Settings → Webhooks et choisissez les événements à recevoir :

Événement	Envoyé quand
consent.created	Un visiteur enregistre un nouveau choix
consent.updated	Un visiteur modifie un choix antérieur
scan.completed	Un scan des cookies se termine
scan.new_items	Un scan détecte des cookies ou des traceurs à vérifier
usage.threshold	L’espace de travail atteint 80 % ou 100 % de ses consentements enregistrés mensuels

Chaque envoi est une requête POST avec un corps JSON et un en-tête Cookiesh-Signature. Cet en-tête contient un horodatage et une signature HMAC-SHA256 de timestamp.body, calculée avec le secret de signature de votre point de terminaison. Vérifiez-la avant de faire confiance aux données reçues :

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

Répondez avec un statut 2xx dans un délai de 10 secondes. Les envois en échec sont relancés avec un délai exponentiel pendant 24 heures au maximum. Un même événement peut arriver plusieurs fois : utilisez son id pour ignorer les doublons.