Banner design

The banner design endpoints expose the same settings as the banner designer in the dashboard. Every path sits under one banner:

https://cookiebeam.com/api/v1/banners/{bannerId}/design/…

bannerId is the banner's internal ID, as returned by GET /api/v1/banners. Every operation is also available as an MCP tool with the name listed below; both run the same checks.

Writes change the draft only. Nothing you change here reaches visitors until the banner is published from the dashboard. There is no publish endpoint yet: the banners:publish scope is reserved.

How these endpoints differ

• The key acts for its creator. Each call re-checks that the member who created the key is still active and may read (and, for writes, edit) this part of this banner. See Who a key acts for.
• Scopes. Reads need banners.design:read, writes banners.design:write; banners:read and banners:write also satisfy them. Deleting, duplicating and setting the default theme need banners:admin.
• Test keys may read and change drafts. They may not delete or duplicate themes, set the default theme, store or remove logo files, or start site captures and style matches (HTTP 403 test_key_production_forbidden).
• Versioned writes. PATCH, PUT and DELETE on a theme or theme section need If-Match. See Versioned writes.
• Extra rate limits. Writes are limited to 120 per minute per key; logo import, site capture, style match and refine to 20 per hour per banner. See Errors and rate limits.
• Plan features. Some settings need a plan feature (advanced design, custom CSS, branding removal, site capture). A change that needs a feature your plan lacks returns HTTP 403 plan_required with details.feature. Applying a preset is the exception: it applies only the parts your plan includes.

Themes

themeId is a theme UUID, or default for the banner's default theme.

A theme document:

{
  "id": "0c6c1c3e-2f0a-4b8e-9d55-7e1f2a3b4c5d",
  "bannerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Default Theme",
  "isDefault": true,
  "themeConfig": {
    "mode": "opt-in",
    "guiOptions": {
      "consentModal": { "layout": "box", "position": "bottom right" },
      "preferencesModal": { "layout": "box", "position": "middle center", "controlStyle": "toggle" },
      "darkMode": "auto"
    },
    "categories": {
      "necessary": { "enabled": true, "readOnly": true },
      "analytics": { "enabled": false, "readOnly": false }
    },
    "branding": { "position": "left", "showBranding": true }
  },
  "cssVariables": { "--cc-btn-primary-bg": "#1d4ed8" },
  "customCss": null,
  "customFeatures": {},
  "createdAt": "2026-09-01T10:00:00.000Z",
  "updatedAt": "2026-10-20T08:30:00.000Z"
}

POST /design/themes takes the dashboard's theme input. All fields are optional:

curl -X POST https://cookiebeam.com/api/v1/banners/3fa85f64-5717-4562-b3fc-2c963f66afa6/design/themes \
  -H "Authorization: Bearer $COOKIEBEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "Autumn campaign", "isDefault": false }'

Theme sections

Each section is a slice of one theme with its own read, its own write and its own ETag. Writes to these paths are JSON merge patches (RFC 7396): send only the keys to change, and send null to remove a key so its default applies. Custom CSS is the exception: it is replaced as a whole with PUT.

Allowed values for the layout section:

The OpenAPI document at /api/v1/openapi.json lists the full schema of every section, including every colour variable.

Versioned writes

Read a section first. The response carries an ETag:

curl -i https://cookiebeam.com/api/v1/banners/3fa85f64-5717-4562-b3fc-2c963f66afa6/design/themes/default/layout \
  -H "Authorization: Bearer $COOKIEBEAM_API_KEY"

HTTP/1.1 200 OK
ETag: "design.layout:q3VZ1m0rXgk8Jw2nT4bYfA"

{
  "data": {
    "themeConfig": {
      "disablePageInteraction": false,
      "guiOptions": {
        "consentModal": { "layout": "box", "position": "bottom right" },
        "preferencesModal": { "layout": "box", "position": "middle center", "controlStyle": "toggle" }
      }
    }
  },
  "version": "v1"
}

Send the change with that value as If-Match:

curl -X PATCH https://cookiebeam.com/api/v1/banners/3fa85f64-5717-4562-b3fc-2c963f66afa6/design/themes/default/layout \
  -H "Authorization: Bearer $COOKIEBEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "design.layout:q3VZ1m0rXgk8Jw2nT4bYfA"' \
  -d '{ "themeConfig": { "guiOptions": { "consentModal": { "layout": "bar", "position": "bottom" } } } }'

The response is the section after the change, with the new ETag. If someone changed the section after your read, the write is refused:

{
  "data": {
    "error": "The resource was changed by another writer. Read it again and retry.",
    "code": "conflict",
    "details": { "currentEtag": "\"design.layout:Hk2pW9sQe1VtYc0uRz7mLb\"" },
    "requestId": "9b2e5f0c-8d7a-4e0b-9c1d-2f3a4b5c6d7e"
  },
  "version": "v1"
}

Read again, re-apply your change and retry with the new ETag. If-Match: * skips the check and overwrites whatever is stored. A write without If-Match returns HTTP 428 precondition_required. A theme used by an active A/B test may be locked: HTTP 409 resource_locked, with the test named in details.

Presets

Logo files

Logo files are stored per banner and served from the CDN. Storing one returns its URL; set that URL on a theme with the logo settings section, then publish.

The three POST operations return HTTP 201:

{
  "data": {
    "url": "https://cdn.cookiebeam.com/…/logo.svg",
    "contentType": "image/svg+xml",
    "bytes": 4210
  },
  "version": "v1"
}

Test keys cannot call these four operations, because the files are written to the live CDN.

Match your website

These operations capture your homepage, propose banner styles that match it, and save a proposal as a new theme. They need the site capture plan feature, and test keys cannot start captures or matches.

A typical flow: start a capture, poll GET /design/site-capture until status is ready, run a match, apply the proposal you like, then make the new theme the default (or edit it further) and publish from the dashboard.

Errors

Besides the common errors, these endpoints return: