API Reference: RESTful Endpoints, Rate Limit

Q: When will webhooks be available?

Webhook support is on the Q4 2026 roadmap. It is not available yet; the planned event types will be announced later.

Q: What happens if the rate limit is exceeded?

A 429 Too Many Requests is returned. The Retry-After header indicates how many seconds you need to wait. Exponential backoff is recommended for burst protection.

Getting Started

Base URL and Authentication

All API calls are made over HTTPS via the base URL below. HTTP requests are redirected to HTTPS with a 301 redirect.

Base URL

https://cerez.io/api/v1

Authentication: Bearer Token

Send your API key in the Authorization header with the Bearer prefix. You can obtain your API key from the Admin panel > Installation page.

curl https://cerez.io/api/v1/banner/YOUR_API_KEY \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

Security warning: Never share your secret key in browser-side code or public repositories. Use it only in secure server environments.

GET

`/api/v1/banner/{api_key}`

Returns the active banner configuration for a domain. The SDK calls this endpoint on every page load; the response is cached server-side for 5 minutes.

Path Parameter

Parameter	Type	Description
`api_key`	string	The public API key for your domain (required)

Query Parameters (optional)

Parameter	Type	Description
`lang`	string	`tr` \| `en` \| `de` (banner language; default: domain setting)
`preview`	boolean	If `true`, no consent cookie is written (for live testing in the Banner Builder)

Example Request

curl https://cerez.io/api/v1/banner/pk_live_abc123 \
  -H "Authorization: Bearer sk_live_xyz789"

const response = await fetch(
    'https://cerez.io/api/v1/banner/pk_live_abc123',
    { headers: { 'Authorization': 'Bearer sk_live_xyz789' } }
);
const banner = await response.json();

$response = Http::withToken('sk_live_xyz789')
    ->get('https://cerez.io/api/v1/banner/pk_live_abc123');
$banner = $response->json();

Successful Response 200 OK

{
  "success": true,
  "data": {
    "domain": "example.com",
    "position": "bottom",
    "theme": "modern",
    "language": "tr",
    "texts": {
      "title": "Çerez Tercihleriniz",
      "description": "Sitemiz deneyiminizi iyileştirmek için çerez kullanır...",
      "accept_all": "Tümünü Kabul Et",
      "reject_all": "Tümünü Reddet"
    },
    "categories": [
      { "id": "necessary", "required": true },
      { "id": "analytics", "required": false },
      { "id": "marketing", "required": false }
    ],
    "consent_expiry_days": 180,
    "products": { "cookie": true, "accessibility": false }
  }
}

POST

`/api/v1/consent/log`

Records the user's consent decision on the server. The record is retained for 90 days to meet the KVKK and GDPR burden of proof.

Body Parameters (JSON)

Parameter	Type	Description
`api_key`	string	Public API key (required)
`session_id`	string	Anonymous user session ID (required)
`categories`	object	`{ necessary, analytics, marketing, functional }` (boolean values)
`action`	string	`accept_all` \| `reject_all` \| `custom`
`page_url`	string	The URL of the page where the banner was shown
`user_agent`	string	Captured automatically; sending it manually is optional

Example Request

curl -X POST https://cerez.io/api/v1/consent/log \
  -H "Authorization: Bearer sk_live_xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "pk_live_abc123",
    "session_id": "sess_a1b2c3d4",
    "categories": { "necessary": true, "analytics": true, "marketing": false },
    "action": "custom",
    "page_url": "https://example.com/products/123"
  }'

Response 201 Created

{
  "success": true,
  "consent_id": "<string consent ID>",
  "timestamp": "2026-05-31T14:23:11+03:00",
  "expires_at": "2026-11-27T14:23:11+03:00"
}

POST

`/api/v1/heartbeat`

Increments the pageview counter and marks the domain as active. The SDK calls this endpoint once per page load.

Body Parameters

Parameter	Type	Description
`api_key`	string	Public API key
`session_id`	string	Session ID (for unique pageview tracking)
`page_url`	string	Current page URL
`referrer`	string	`document.referrer` value (optional)

Response

{
  "success": true,
  "pageview_count_month": 42183,
  "plan_limit": 100000,
  "usage_percent": 42.18
}

Rate Limiting

Request Limits

Applied per IP address. When the limit is exceeded, the response includes a header indicating the wait time.

500

requests / minute / IP

5 dk

banner cache duration

90 gün

API log retention period

Limit exceeded: A 429 Too Many Requests is returned. The Retry-After header specifies the wait time in seconds. Exponential backoff (1s, 2s, 4s, 8s...) is recommended for burst protection. For a custom rate limit increase on the Enterprise plan, contact the sales team.

Error Codes

HTTP Status Codes

Code	Description	Typical Cause
200	OK	Request successful
201	Created	Record created (consent log)
401	Unauthorized	Bearer token missing or invalid
403	Forbidden	Outside the IP whitelist or plan limit exceeded
404	Not Found	API key or resource not found
422	Unprocessable	Validation error; check the errors field in the response
429	Too Many Requests	Rate limit exceeded (500/min)
500	Server Error	Server-side error; contact support

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key bulunamadı veya devre dışı",
    "details": { "field": "api_key" }
  }
}

Webhook

Event Notifications Q4 2026

Webhook support is on the Q4 2026 roadmap; it is not available yet. The following events are planned. Get in touch for announcements.

consent.given

Triggered when the user gives consent

consent.rejected

Triggered when the user declines

consent.updated

Triggered when preferences are changed

scan.completed

Triggered when a cookie scan completes

scan.failed

Triggered when a scan fails

subscription.expired

Triggered when a subscription ends

pageview.limit_warning

Triggered when pageview usage crosses the 80 percent threshold

a11y.profile_used

Triggered when an accessibility profile is used

FAQ

The questions on your mind

What is the difference between the SDK and the API?

Short answer: The SDK runs in the browser and renders the banner automatically. The API is designed for server-to-server integration; it is used in scenarios such as custom dashboards, mobile apps or server-side consent logging. Most customers use only the SDK.

Is there a batch endpoint?

Short answer: There is currently no batch endpoint. The POST /api/v1/consent/log endpoint is for single calls. Batch support is on the Q4 2026 roadmap.

How does the IP whitelist work?

Short answer: Open the IP Restriction toggle under Admin panel > Installation and enter the allowed IPs (CIDR notation supported: 192.168.1.0/24). Requests outside the whitelist receive a 403 Forbidden. SDK requests coming from the browser are always accepted.

When will webhooks be available?

Short answer: Webhook support is on the Q4 2026 roadmap and is not available yet. The planned event types and signing mechanism will be announced at a later date.

What happens if the rate limit is exceeded?

Short answer: A 429 Too Many Requests is returned. The Retry-After header indicates how many seconds you need to wait. Exponential backoff (1s, 2s, 4s, 8s...) is recommended for burst protection. The rate limit can be raised on the Enterprise plan.

RESTful API: Complete documentation for developers

Base URL and Authentication

Base URL

Authentication: Bearer Token

`/api/v1/banner/{api_key}`

Path Parameter

Query Parameters (optional)

Example Request

Successful Response 200 OK

`/api/v1/heartbeat`

Body Parameters

Response

Request Limits

HTTP Status Codes

Error Response Format

Event Notifications Q4 2026

The questions on your mind

Want to test the API?