---
title: "Banners"
description: "List and create consent banners with the CookieBeam REST API."
url: "https://cookiebeam.com/docs/api-reference/banners"
lang: "en"
---

# 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

```text
GET /api/v1/banners
```

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

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

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

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

```json
{
  "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`, `test_key_read_only`, or `key_restricted` (create only) — see [Authentication](https://cookiebeam.com/docs/api-reference/authentication) |
| 405 | The endpoint does not support the HTTP method used |

A validation failure looks like this:

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