API Reference

Documentation complète de l'API REST Ad Sentinelle.

Base URL

Production: https://adwall-backend-xxxxx.run.app/v1

Authentification

L'API utilise des clés API pour l'authentification :

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://adwall-backend-xxxxx.run.app/v1/sites

Obtenir une clé API

1. Connectez-vous au dashboard
2. Allez dans Paramètres → API
3. Cliquez sur "Générer une clé API"

Endpoints

Sites

Lister les sites

GET /v1/sites

Réponse :

{
  "sites": [
    {
      "id": "677c2846-fed7-4461-b69c-7717bc3be9b4",
      "name": "Mon Site",
      "domain": "monsite.fr",
      "status": "active",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Obtenir un site

GET /v1/sites/:id

Réponse :

{
  "id": "677c2846-fed7-4461-b69c-7717bc3be9b4",
  "name": "Mon Site",
  "domain": "monsite.fr",
  "status": "active",
  "config": {
    "mode": "hard",
    "template_id": "default"
  },
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-02-01T14:20:00Z"
}

Créer un site

POST /v1/sites

Body :

{
  "name": "Mon Nouveau Site",
  "domain": "nouveau-site.fr"
}

Mettre à jour un site

PATCH /v1/sites/:id

Body :

{
  "name": "Nouveau nom",
  "status": "inactive"
}

Supprimer un site

DELETE /v1/sites/:id

---

Analytics

Dashboard metrics

GET /v1/analytics/sites/:id/dashboard

Query params :

Param	Type	Description
days	number	Nombre de jours (défaut: 7)
device	string	Filtrer par device

Réponse :

{
  "period": {
    "start": "2026-02-01",
    "end": "2026-02-08"
  },
  "metrics": {
    "sessions": 45678,
    "adblock_detected": 15234,
    "walls_displayed": 15100,
    "conversions": 4521,
    "conversion_rate": 29.94
  },
  "comparison": {
    "sessions_change": 12.3,
    "conversions_change": 8.2,
    "rate_change": 2.3
  }
}

Timeline des conversions

GET /v1/analytics/sites/:id/conversions

Query params :

Param	Type	Description
days	number	Nombre de jours
granularity	string	hour, day, week

Réponse :

{
  "timeline": [
    {
      "date": "2026-02-01",
      "sessions": 6543,
      "adblock_detected": 2157,
      "conversions": 647,
      "conversion_rate": 30.0
    },
    {
      "date": "2026-02-02",
      "sessions": 6789,
      "adblock_detected": 2311,
      "conversions": 701,
      "conversion_rate": 30.3
    }
  ]
}

A/B Testing results

GET /v1/analytics/sites/:id/ab-testing

Réponse :

{
  "variants": [
    {
      "name": "control",
      "impressions": 5078,
      "conversions": 1269,
      "conversion_rate": 25.0,
      "confidence": 95.2
    },
    {
      "name": "emotional",
      "impressions": 5123,
      "conversions": 1486,
      "conversion_rate": 29.0,
      "confidence": 95.2,
      "is_winner": true
    },
    {
      "name": "alternative",
      "impressions": 5033,
      "conversions": 1258,
      "conversion_rate": 25.0,
      "confidence": 95.2
    }
  ],
  "recommendation": "Use 'emotional' variant"
}

---

Events

Track event (SDK use)

POST /v1/events/track

Body :

{
  "session_id": "abc123-def456",
  "site_id": "677c2846-fed7-4461-b69c-7717bc3be9b4",
  "event_type": "adblock_detected",
  "page_url": "https://monsite.fr/article",
  "metadata": {
    "blocker_type": "ublock",
    "device_type": "desktop"
  }
}

Lister les événements

GET /v1/events/sites/:id

Query params :

Param	Type	Description
event_type	string	Filtrer par type
limit	number	Nombre de résultats
offset	number	Pagination

---

Templates

Lister les templates

GET /v1/templates/sites/:id

Obtenir un template

GET /v1/templates/:id

Créer/Mettre à jour un template

PUT /v1/templates/sites/:id

Body :

{
  "name": "Mon Template",
  "config": {
    "mode": "hard",
    "title": "Bloqueur détecté",
    "messages": ["Message 1", "Message 2"],
    "cta_text": "J'ai désactivé",
    "primary_color": "#8b5cf6",
    "background_color": "#ffffff",
    "logo_url": "https://...",
    "animation": "fade"
  }
}

---

Loader

Obtenir le loader SDK

GET /v1/loader/:siteId.js

Retourne le script SDK configuré pour le site.

---

Codes d'erreur

Code	Description
200	Succès
201	Créé
400	Requête invalide
401	Non authentifié
403	Non autorisé
404	Non trouvé
429	Rate limit dépassé
500	Erreur serveur

Format d'erreur

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Le champ 'domain' est requis",
    "details": {
      "field": "domain",
      "reason": "required"
    }
  }
}

Rate Limiting

Endpoint	Limite
/v1/events/track	1000/min
Autres endpoints	100/min

Headers de réponse :

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707400000

SDK JavaScript

Méthodes exposées

// Initialisation (automatique via loader)
Ad Sentinelle.init({ siteId: '...' });

// Forcer une détection
Ad Sentinelle.check();

// Obtenir l'ID de session
Ad Sentinelle.getSessionId();

// Forcer l'affichage (debug)
Ad Sentinelle.forceDisplay();

// Masquer le wall
Ad Sentinelle.hide();

Exemples

cURL

# Obtenir les métriques
curl -X GET \
  "https://adwall-backend.../v1/analytics/sites/SITE_ID/dashboard?days=7" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch(
  'https://adwall-backend.../v1/analytics/sites/SITE_ID/dashboard?days=7',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);
const data = await response.json();

Python

import requests

response = requests.get(
    'https://adwall-backend.../v1/analytics/sites/SITE_ID/dashboard',
    params={'days': 7},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

Postman

Une collection Postman est disponible sur demande auprès du support.