Brand Kit API

The Brand Kit API reads and changes the brand kit of the token’s channel, as set on Settings → Brand Kit (see Drag-and-Drop Email Builder). Every new block email starts from the brand kit, and the unsubscribe page, the confirmation page and new opt-in forms can use it too.

Whether those pages and new opt-in forms use the brand kit is a channel setting: match_brand_kit in the unsubscribe_page, confirmation_page and opt_in_forms groups of the Channel Settings API.

Required Permissions

• Templates read or Channel Settings read: get the brand kit
• Channel Settings write: change the brand kit

Channel Settings write is off on every token until you tick it, including tokens created before 2.46.0. Templates write does not change the brand kit. Set the permissions under Access Tokens (and Admin API Tokens). See API Authentication.

An admin API token must name the channel with broadcast_channel_id, as a query parameter for GET and in the body for PATCH.

Brand Kit Object

{
  "colors": {
    "page_background": "#f4f4f5",
    "body_background": "#ffffff",
    "text": "#18181b",
    "muted": "#71717a",
    "link": "#2563eb",
    "accent": "#ff5500",
    "button_text": "#ffffff"
  },
  "typography": {
    "font": "georgia",
    "font_stack": "Georgia,'Times New Roman',Times,serif"
  },
  "layout": { "width": 600, "radius": 4 },
  "brand": {
    "logo_url": "https://your-broadcast-domain.com/files/eyJfcmFpbHMi...--3f2a...-logo.png",
    "logo_width": 180,
    "website_url": "https://acme.example",
    "social_links": [ { "network": "x", "url": "https://x.com/acme" } ],
    "social_icon_style": "dark"
  }
}

Defaults are filled in, so every field is always present.

Get the Brand Kit

GET /api/v1/channel/design

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-broadcast-domain.com/api/v1/channel/design

Returns 200 with the brand kit object.

Update the Brand Kit

PATCH /api/v1/channel/design

Send the values to change inside channel_design, in the same shape GET returns. Only what you send changes:

• A value you leave out stays as it is.
• Send "" or null to put a value back to its default. For brand.logo_url, null removes the logo.
• brand.social_links replaces the whole list. A link without a url is left out, and [] removes every link.

You can send back the whole object that GET returned. The read-only typography.font_stack and layout.width are then ignored with no warning, because they did not change.

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "channel_design": {
      "colors": { "accent": "#ff5500", "button_text": "#ffffff" },
      "typography": { "font": "georgia" },
      "brand": {
        "website_url": "https://acme.example",
        "social_links": [ { "network": "instagram", "url": "https://instagram.com/acme" } ]
      }
    }
  }' \
  https://your-broadcast-domain.com/api/v1/channel/design

Returns 200 with the whole brand kit after the change, so you can check what was saved.

The logo

The API does not upload images. To set the logo:

1. Upload the image under File Assets in Broadcast, for this channel.
2. Copy its public URL.
3. Send it as brand.logo_url.

Broadcast reads only the path of the URL to find the image in the channel’s file library. It never downloads a URL. The file must be a PNG, JPEG or GIF image, the same types the Brand Kit page offers. An image from another website, a file the channel cannot use, or a file of another type is refused with a 422.

{ "channel_design": { "brand": { "logo_url": "https://your-broadcast-domain.com/files/eyJfcmFpbHMi...--3f2a...-logo.png", "logo_width": 200 } } }

Errors

A 422 saves nothing. There are two kinds.

A value that is not one of the allowed values (typography.font, brand.social_icon_style, a network in brand.social_links), a number that is not a whole number (layout.radius, brand.logo_width), or a logo URL that is not an image in the channel’s file library:

{
  "error": "Unprocessable Content",
  "message": "channel_design.typography.font must be one of system, helvetica, georgia, verdana, mono, inter"
}

{
  "error": "Unprocessable Content",
  "message": "channel_design.brand.logo_url must be the URL of an image in this channel's file library, as GET /api/v1/channel/design returns it"
}

A value that fails validation. These are the same rules as the Brand Kit page: a colour that is not a six-digit hex colour, a layout.radius outside 0 to 32, a brand.logo_width outside 40 to 400, or a website or social link that is not an http:// or https:// URL:

{
  "error": "Design settings accent color must be a hex value such as #2563eb"
}

A body without a channel_design object returns 400. A token without the permission returns 401.

Warnings

The response can carry a warnings array (see API Response Warnings). The code is unrecognized_parameter in these cases:

• A key that is not part of the brand kit, at any depth, for example channel_design.colors.glow or channel_design.brand.tagline. The key is ignored and the rest is saved.
• A brand kit switch: channel_design.brand.apply_to_unsubscribe, apply_to_confirmation or apply_to_opt_in_forms. The warning names the key to use instead, for example channel_settings.opt_in_forms.match_brand_kit in the Channel Settings API.
• A read-only value (typography.font_stack, layout.width) that differs from the brand kit.

{
  "colors": { "...": "..." },
  "warnings": [
    {
      "code": "unrecognized_parameter",
      "param": "channel_design.layout.width",
      "message": "width is read-only: the email width is chosen per design, not in the brand kit, so it was ignored."
    }
  ]
}