RESTful API: Complete documentation for developers

Base URL

https://cerez.io/api/v1

OpenAPI 3.1 Specification

Machine-readable OpenAPI 3.1 definition of all endpoints. Import it into Postman, Insomnia, code generators and interactive clients.

Authentication: Public API Key

The SDK API uses a public API key: passed in the URL path for GET requests and in the request body for POST requests. This key is used by the browser-side SDK, so it is expected to be visible on the client. The Authorization: Bearer header is not used. You can get your API key from admin panel > Installation.

curl https://cerez.io/api/v1/banner/YOUR_API_KEY

Body Parameters (JSON)

Example Request

curl -X POST https://cerez.io/api/v1/consent/log \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "visitor_id": "vis_a1b2c3d4",
    "action": "partial",
    "categories_accepted": { "necessary": true, "analytics": true, "marketing": false },
    "device_type": "desktop"
  }'

await fetch('https://cerez.io/api/v1/consent/log', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    visitor_id: 'vis_a1b2c3d4',
    action: 'partial',
    categories_accepted: { necessary: true, analytics: true, marketing: false }
  })
});

import requests
requests.post('https://cerez.io/api/v1/consent/log',
  headers={'Accept': 'application/json'},
  json={
    'api_key': 'YOUR_API_KEY',
    'visitor_id': 'vis_a1b2c3d4',
    'action': 'partial',
    'categories_accepted': {'necessary': True, 'analytics': True, 'marketing': False}
  })

Response 200 OK

{ "status": "ok" }

Note: add the Accept: application/json header to the request so validation errors return 422.

Cookies and Consent

Accessibility

TCF and Vendor List

Telemetry and System

Response Envelopes

For historical reasons, SDK endpoints use different response envelopes; these shapes are preserved for backward compatibility. Parse responses according to the table below.

API Version

You can fetch the current API and SDK versions along with TCF/GVL metadata at runtime from the GET /api/v1/meta endpoint (public, read-only).

GET /api/v1/meta

{
  "api_version": "1.0.0",
  "sdk_version": "2.6.2",
  "products": ["cookie", "accessibility"],
  "tcf": { "gvl_version": 123, "policy_version": 5 },
  "docs": "https://cerez.io/kaynaklar/api-referans"
}

OpenAPI 3.1 Specification

All 18 SDK endpoints in machine-readable form (Postman import / client generation).

Base URL

https://cerez.io/api/mgmt/v1

Authentication: Bearer secret_key

Send your secret key in the Authorization: Bearer header. Get the secret key from admin panel > Installation > API and store it ONLY in a secure server environment; never place it on the client.

curl https://cerez.io/api/mgmt/v1/domain \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Endpoints

Successful Response 200 OK

GET /api/mgmt/v1/domain

{
  "data": {
    "id": 42,
    "site_name": "Örnek",
    "domain_url": "https://example.com",
    "products": ["cookie", "accessibility"],
    "subscriptions": [
      { "product": "cookie", "plan_slug": "cookie_pro", "status": "active" }
    ],
    "settings": { "kvkk_enabled": true, "consent_expiry_days": 180 }
  },
  "meta": { "api": "mgmt/v1", "generated_at": "2026-06-30T12:00:00+00:00" }
}

Webhooks HMAC-SHA256

When low-frequency events occur, a signed POST is sent to your registered endpoints: scan.completed, cookies.new_found, scan.error. High-volume consent events are not sent via webhook.

Example payload and headers

POST https://ornek.com/webhooks/cerez
X-Cerez-Event: scan.completed
X-Cerez-Timestamp: 1782475200
X-Cerez-Signature: sha256=3a7b...e0

{
  "event": "scan.completed",
  "created_at": "2026-06-30T12:00:00+00:00",
  "domain_id": 42,
  "data": { "total_cookies": 31, "new_cookies": 2 }
}

Signature verification (receiver side)

The signature is derived from the timestamp and the raw body. Verify with a constant-time comparison and confirm the timestamp is not older than 5 minutes (replay protection).

// Node.js
const crypto = require('crypto');
const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(timestamp + '.' + rawBody)
  .digest('hex');
const ok = crypto.timingSafeEqual(
  Buffer.from(expected), Buffer.from(signatureHeader)
);

// PHP
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
$ok = hash_equals($expected, $signatureHeader);

DSAR (Data Subject Requests) KVKK m.11 / GDPR m.15-17

Helps you respond to access and erasure requests for a visitor's data. Erasure = anonymization: direct identifiers (visitor_id, external_id, user_agent, region) are removed; consent proof (action, categories, TCF string, timestamps) is PRESERVED. You verify the visitor's identity.

Anonymization is two-step (accidental-deletion protection)

# 1. Önizleme (confirm_token yok) — hiçbir şey değişmez
curl -X POST https://cerez.io/api/mgmt/v1/dsar/erasure \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "visitor_id": "vis_a1b2c3" }'
# -> { "data": { "dry_run": true, "matched_count": 3, "confirm_token": "..." } }

# 2. Uygula (önizlemeden gelen confirm_token ile)
curl -X POST https://cerez.io/api/mgmt/v1/dsar/erasure \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "visitor_id": "vis_a1b2c3", "confirm_token": "..." }'
# -> { "data": { "dry_run": false, "affected_count": 3 } }

If the record count changes between preview and apply, the token becomes invalid (409). Access and erasure are written to the audit log on every successful call. This tool helps you meet your compliance obligations; consult qualified counsel for legal validity.

OpenAPI 3.1 Specification

Machine-readable OpenAPI 3.1 definition of the Management API (Postman/codegen).