API overview

The CookieBeam REST API lets you manage banners and consent records programmatically. Endpoints are served under a versioned path from your account's application host. It looks like:

https://<your-app-host>/api/v1/

Versioning

The API version lives in the URL path. Current endpoints are mounted at static /api/v1/... paths, and v1 is the only version that exists — there is no unversioned variant of these routes, so /api/banners returns HTTP 404, as does a path for a version that is not deployed, such as /api/v2/banners.

Do not send an api-version header: on the versioned paths it has no effect, because the path alone determines the version.

Response envelope

Successful responses wrap the payload in a data field and echo the version:

{
  "data": {
    "banners": []
  },
  "version": "v1"
}

Responses produced by the versioned wrapper also carry two headers:

• API-Version — the version that handled the request.
• API-Supported-Versions — the versions the server supports, currently v1.

Do not build monitoring that assumes these headers on every response: error responses built before the versioned wrapper runs (for example an uncaught handler error) do not carry them.

Authentication

Most endpoints authenticate with an API key sent as a bearer token:

Authorization: Bearer cb_live_your_key_here

Keys carry an explicit list of scopes and are limited by plan-based rate limits. See Authentication for key formats, scopes, and the live vs test distinction. The banner endpoints also accept a dashboard session, which is how the CookieBeam dashboard itself calls them.

Rate limits

API-key requests are limited per key over a 15-minute window; the limit depends on your plan. Responses that complete the key-authentication flow carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; requests rejected before rate limiting runs (plan, scope, or key failures) and some server-error paths do not. Exhausting the limit returns HTTP 429 with a Retry-After header. See Errors and rate limits.

Health check

GET /api/v1/health returns a minimal status payload without authentication:

{
  "data": {
    "status": "ok"
  },
  "version": "v1"
}

Use it to confirm reachability before diagnosing authentication or scope problems.

Safe retries with Idempotency-Key

POST /api/v1/banners, POST /api/v1/consent/log and PUT /api/v1/consent/subjects/state accept an optional Idempotency-Key header (1–255 printable ASCII characters, for example a UUID you generate per operation). Send the same key when you retry after a timeout or network error:

• The first request runs. Its result is stored for 24 hours from that request.
• A retry with the same key and the same request (method, path and JSON body; key order in the body does not matter) does not run again. It returns the stored status and body with the header Idempotent-Replayed: true. Authentication, scopes and rate limits are checked again on every retry.
• The same key with a different request returns 422 idempotency_key_reused.
• If the first request is still running, a retry waits up to 5 seconds, then returns 409 idempotency_in_progress with Retry-After.
• A request that fails with a 5xx error stores nothing, so a retry runs it again.
• A retry after the 24-hour window is treated as a new operation.

Keys are scoped to the API key that sent them. Requests without the header behave exactly as before.

In this section

• Authentication — keys, environments, and scopes.
• Banners — list and create banners.
• Consent — record consent and sync consent state across devices.
• Browser API — the window.CookieBeam runtime API exposed by the banner script.
• Webhooks — event delivery to your endpoints.
• Errors and rate limits — error codes, 429 behavior, and retry guidance.