Banners

List and create consent banners with the CookieBeam REST API.

The banners endpoints list your team's banners and create new ones. Both also accept a dashboard session instead of an API key — that is how the CookieBeam dashboard calls them — but integrations should use a key.

List banners

GET /api/v1/banners

Requires the banners:read scope. Returns every banner on the key's team:

{
  "data": {
    "banners": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Main site",
        "domain": "https://example.com",
        "isActive": true,
        "configuration": {
          "layout": "banner",
          "position": "bottom",
          "primaryColor": "#000000",
          "secondaryColor": "#ffffff",
          "textColor": "#333333",
          "accentColor": "#007bff"
        },
        "compliance": {
          "gdpr": true,
          "ccpa": false,
          "lgpd": false
        },
        "createdAt": "2026-08-01T12:00:00.000Z",
        "updatedAt": "2026-08-01T12:00:00.000Z"
      }
    ]
  },
  "version": "v1"
}

Create a banner

POST /api/v1/banners

Requires the banners:write scope (a live key; test keys are read-only). The body:

Field	Type	Required	Notes
`name`	string	yes	1–255 characters
`domain`	string	yes	Bare hostnames are normalized to an `https://` URL; the result must be a valid domain (or `localhost`)
`configuration`	object	yes	Appearance settings; every field inside has a default
`configuration.layout`	string	no	`banner` (default), `modal`, or `inline`
`configuration.position`	string	no	`top`, `bottom` (default), or `center`
`configuration.primaryColor`	string	no	Default `#000000`
`configuration.secondaryColor`	string	no	Default `#ffffff`
`configuration.textColor`	string	no	Default `#333333`
`configuration.accentColor`	string	no	Default `#007bff`
`gdprEnabled`	boolean	no	Default `true`
`ccpaEnabled`	boolean	no	Default `false`
`lgpdEnabled`	boolean	no	Default `false`

Example request:

{
  "name": "Main site",
  "domain": "example.com",
  "configuration": {
    "layout": "banner",
    "position": "bottom"
  },
  "gdprEnabled": true
}

A successful create returns HTTP 201 with the new banner in the same shape as the list above:

{
  "data": {
    "banner": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Main site",
      "domain": "https://example.com",
      "isActive": true,
      "configuration": {
        "layout": "banner",
        "position": "bottom",
        "primaryColor": "#000000",
        "secondaryColor": "#ffffff",
        "textColor": "#333333",
        "accentColor": "#007bff"
      },
      "compliance": { "gdpr": true, "ccpa": false, "lgpd": false },
      "createdAt": "2026-08-13T12:00:00.000Z",
      "updatedAt": "2026-08-13T12:00:00.000Z"
    }
  },
  "version": "v1"
}

Creation also registers the domain for consent collection and prepares the banner's production environment, in the same transaction, so a banner created through the API is ready for the same publish and install flow as one created in the dashboard.

Errors

HTTP status	Cause
400	Validation failed. The body includes a `details` array describing each invalid field
401	No API key and no dashboard session, or an invalid key
403	`plan_required`, `missing_scope`, or `test_key_read_only` — see Authentication
405	The endpoint does not support the HTTP method used

A validation failure looks like this:

{
  "data": {
    "error": "Validation failed",
    "details": [
      { "message": "Domain must be a valid domain (e.g., example.com)" }
    ]
  },
  "version": "v1"
}