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.

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.