# Brand Kit API

> Read and change a channel's brand kit through the Broadcast API, including colours, font, corner radius, logo, website and social links.

Source: https://sendbroadcast.net/docs/api-channel-design

Note

**Requires Broadcast 2.46.0 or later** to change the brand kit (`PATCH`). Reading it (`GET`) also works on earlier versions.

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](https://sendbroadcast.net/docs/block-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](https://sendbroadcast.net/docs/api-channel-settings).

## 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](https://sendbroadcast.net/docs/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

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

| Field | Type | Description |
|-------|------|-------------|
| `colors.page_background`, `colors.body_background`, `colors.text`, `colors.muted`, `colors.link`, `colors.accent`, `colors.button_text` | string | Six-digit hex colours, such as `#2563eb`. Broadcast stores them in lower case. |
| `typography.font` | string | `system`, `helvetica`, `georgia`, `verdana`, `mono` or `inter`. |
| `typography.font_stack` | string | The email-safe `font-family` for `font`. Read-only. |
| `layout.width` | integer | The default email width in pixels. Read-only: you set the width per design in the editor. |
| `layout.radius` | integer | The corner radius of buttons and boxes, from `0` to `32` pixels. |
| `brand.logo_url` | string or null | The public URL of the logo, or `null` when there is no logo. |
| `brand.logo_width` | integer | The display width of the logo, from `40` to `400` pixels. |
| `brand.website_url` | string or null | Your website. An `http://` or `https://` URL. |
| `brand.social_links` | array | `{ "network", "url" }` pairs. `network` is `x`, `instagram`, `facebook`, `linkedin`, `youtube`, `tiktok`, `threads`, `bluesky`, `mastodon` or `website`; `url` is an `http://` or `https://` URL. |
| `brand.social_icon_style` | string | `dark`, `light` or `color` (brand colours). |

## Get the Brand Kit

`GET /api/v1/channel/design`

```bash
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.

```bash
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`.

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

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

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

```json
{
  "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](https://sendbroadcast.net/docs/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](https://sendbroadcast.net/docs/api-channel-settings).
- A read-only value (`typography.font_stack`, `layout.width`) that differs from the brand kit.

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