API Reference

Complete documentation of the Ad Sentinelle REST API.

Base URL

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

Authentication

The API uses API keys:

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

Get API Key

1. Log in to dashboard
2. Go to Settings → API
3. Click "Generate API Key"

Endpoints

Sites

List Sites

GET /v1/sites

Response:

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

Get Site

GET /v1/sites/:id

Dashboard Metrics

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

Query params:

Param	Type	Description
days	number	Days to include (default: 7)
device	string	Filter by device

Response:

{
  "period": {
    "start": "2026-02-01",
    "end": "2026-02-08"
  },
  "metrics": {
    "sessions": 45678,
    "adblock_detected": 15234,
    "conversions": 4521,
    "conversion_rate": 29.94
  }
}

Conversions Timeline

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

Query params:

Param	Type	Description
days	number	Number of days
granularity	string	hour, day, week

A/B Testing Results

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

Response:

{
  "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
    }
  ]
}

Events

Track Event

POST /v1/events/track

Body:

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

List Events

GET /v1/events/sites/:id

Query params:

Param	Type	Description
event_type	string	Filter by type
limit	number	Results count
offset	number	Pagination

Error Codes

Code	Description
200	Success
201	Created
400	Invalid request
401	Not authenticated
403	Not authorized
404	Not found
429	Rate limit exceeded
500	Server error

Error Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Field 'domain' is required",
    "details": {
      "field": "domain",
      "reason": "required"
    }
  }
}

Rate Limiting

Endpoint	Limit
/v1/events/track	1000/min
Other endpoints	100/min

Headers:

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

SDK Methods

// Initialize
AdSentinelle.init({ siteId: '...' });

// Force detection
AdSentinelle.check();

// Get session ID
AdSentinelle.getSessionId();

// Force display (debug)
AdSentinelle.forceDisplay();

// Hide wall
AdSentinelle.hide();

Examples

cURL

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

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

Postman collection available on request.