---
title: "API overview"
description: "Base URL, versioning, response envelope, and authentication model for the CookieBeam REST API."
url: "https://cookiebeam.com/docs/api-reference/overview"
lang: "en"
---

# API overview

Base URL, versioning, response envelope, and authentication model for the CookieBeam REST API.

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:

```text
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:

```json
{
  "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:

```text
Authorization: Bearer cb_live_your_key_here
```

Keys carry an explicit list of scopes and are limited by plan-based rate limits. See [Authentication](https://cookiebeam.com/docs/api-reference/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](https://cookiebeam.com/docs/api-reference/errors-and-limits).

## Health check

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

```json
{
  "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](https://cookiebeam.com/docs/api-reference/authentication) — keys, environments, and scopes.
- [Banners](https://cookiebeam.com/docs/api-reference/banners) — list and create banners.
- [Consent](https://cookiebeam.com/docs/api-reference/consent) — record consent and sync consent state across devices.
- [Browser API](https://cookiebeam.com/docs/api-reference/browser-api) — the `window.CookieBeam` runtime API exposed by the banner script.
- [Webhooks](https://cookiebeam.com/docs/api-reference/webhooks) — event delivery to your endpoints.
- [Errors and rate limits](https://cookiebeam.com/docs/api-reference/errors-and-limits) — error codes, 429 behavior, and retry guidance.