--- title: "Create Brand" method: POST path: "/brands" tags: ["Brands"] --- # Create Brand `POST /brands` ## Request - Base URL: `https://api.wistia.com/modern` - URL: `https://api.wistia.com/modern/brands` - Auth: HTTP bearer Creates a brand. A brand is a saved set of branding options (colors, fonts, logos, and layout) that can then be applied to media, folders, and channels. `name` is required; every other field is optional and left unset when omitted. A new brand isn't applied to anything — it has no effect until you apply it to a resource with `POST /brands/{brandId}/apply`. Accounts whose plan doesn't include multiple brands can only hold one brand. ## Requires api token with one of the following permissions ``` All data ``` Tokens with the "Act with a team member's permissions" permission (`all:delegate_to_contact_permissions` scope) can also be used. Requests made with such a token are authorized using the permissions of the contact assigned to the token. An [expiring access token](https://docs.wistia.com/reference/post_expiring-token) created with the `all:delegate_to_contact_permissions` scope and an `account` authorization granting the `create-brands` permission can also be used. The new brand is not covered by the token that created it, so follow-up requests need a token whose authorizations name the returned hashed id. ## Headers - `X-Wistia-API-Version` string, required ## Request body - object: Brand attributes to write. Every field is optional on update and only the fields you send are changed — send an explicit `null` to unset one. `name` is required when creating a brand. The writable field names match the ones a brand is read back with, so an edit can reuse the values from a `GET`. The read-only fields (`id`, `is_default`, `created`, `updated`) are not accepted here and must be dropped from a body built that way. Colors accept three-character hex shorthand and store the expanded six-character form, so `#abc` is read back as `#aabbcc`. **Logos cannot be uploaded through the API.** `page_logo.url` and `player_logo.url` must be Wistia delivery URLs (`https://embed-ssl.wistia.com/deliveries/.png`) for images already in the account — for example a URL returned by a previous request to this endpoint. Any other URL is rejected, because the brand is applied by resolving that image out of Wistia's own storage. To add a new logo image, upload it in the Wistia app first. - `name` string: The brand's display name. Renaming the account-level default brand is ignored; its name is managed by Wistia. - `primary_color` union: The primary brand color, used for primary buttons and the player playbar. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples. - string - array[] - unknown[] - unknown - `page_background_color` union: The brand color used for page backgrounds. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples. - string - array[] - unknown[] - unknown - `body_font_family` string, nullable: The brand font family for body text. - `headline_font_family` string, nullable: The brand font family for headlines. - `button_font_family` string, nullable: The brand font family for buttons. - `border_radius` integer, nullable: The border radius in pixels for rounded corners. - `contrast_icons` 'enabled' | 'disabled' | 'unset' | 'null', nullable: Controls whether the player icon color is always white or uses an accessible contrast color when necessary. - `opaque_controls` 'enabled' | 'disabled' | 'unset' | 'null', nullable: Controls the opacity of the video player control bar and big play button. - `page_logo` object, nullable: The brand logo used for pages. `url` must be a Wistia delivery URL — see the note on uploading below. On accounts without custom branding the player logo is ignored, but the page logo is always applied. - `url` string: The Wistia delivery URL of the logo image, e.g. `https://embed-ssl.wistia.com/deliveries/abc123def456.png`. When writing, this must reference an image already in the account; the API cannot upload one. - `dimensions` object, nullable - `width` integer - `height` integer - `size` number, nullable: The size multiplier of the logo. - `player_logo` object, nullable: The brand logo used for the player. `url` must be a Wistia delivery URL — see the note on uploading below. Ignored on accounts whose plan doesn't include custom branding. - `url` string: The Wistia delivery URL of the logo image, e.g. `https://embed-ssl.wistia.com/deliveries/abc123def456.png`. When writing, this must reference an image already in the account; the API cannot upload one. - `dimensions` object, nullable - `width` integer - `height` integer - `size` number, nullable: The size multiplier of the logo. ## Response `201` Brand created successfully - object: A brand is a saved set of branding options — colors, fonts, logos, and layout — that can be applied to media, folders, and channels. - `id` string: A unique alphanumeric identifier for this brand. - `name` string: The brand's display name. - `is_default` boolean: Whether this brand is the account-level default, applied to content that has no more specific brand. - `created` string, date-time: The date the brand was originally created. - `updated` string, date-time: The date the brand was last updated. - `primary_color` union: The primary brand color, used for primary buttons and the player playbar. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples. Null when unset. - string - array[] - unknown[] - unknown - `page_background_color` union: The brand color used for page backgrounds. Either a hex color string or a gradient represented as an array of [hexColor, percentage] tuples. Null when unset. - string - array[] - unknown[] - unknown - `body_font_family` string, nullable: The brand font family for body text. Null when unset. - `headline_font_family` string, nullable: The brand font family for headlines. Null when unset. - `button_font_family` string, nullable: The brand font family for buttons. Null when unset. - `border_radius` integer, nullable: The border radius in pixels for rounded corners. Null when unset. - `contrast_icons` 'enabled' | 'disabled' | 'unset' | 'null', nullable: Controls whether the player icon color is always white or uses an accessible contrast color when necessary. - `opaque_controls` 'enabled' | 'disabled' | 'unset' | 'null', nullable: Controls the opacity of the video player control bar and big play button. - `page_logo` object, nullable: The brand logo used for pages. Null when unset. - `url` string: The Wistia delivery URL of the logo image, e.g. `https://embed-ssl.wistia.com/deliveries/abc123def456.png`. When writing, this must reference an image already in the account; the API cannot upload one. - `dimensions` object, nullable - `width` integer - `height` integer - `size` number, nullable: The size multiplier of the logo. - `player_logo` object, nullable: The brand logo used for the player. Null when unset. - `url` string: The Wistia delivery URL of the logo image, e.g. `https://embed-ssl.wistia.com/deliveries/abc123def456.png`. When writing, this must reference an image already in the account; the API cannot upload one. - `dimensions` object, nullable - `width` integer - `height` integer - `size` number, nullable: The size multiplier of the logo. - `cursor` string, nullable: A cursor for stable pagination based on current `sort_by` order. You can pass this to `cursor[before]` or `cursor[after]` as a parameter to fetch the records before or after this record in the same sort order. This is only populated if records were fetched with `cursor[enabled]`, or `cursor[before]` or `cursor[after]`. ## Other responses - `400`: Bad request - `401`: Unauthorized, invalid or missing token - `403`: Forbidden, token is valid but account does not have access to feature - `500`: Internal server error ## Changes - **2026-11-03** `b86cb2a7b420`: 1 info - endpoint added [Operation history](https://skmtc.dev/wistia/apis/data-api/changes/brands/post.md) --- [API](https://skmtc.dev/wistia/apis/data-api.md) - [All operations](https://skmtc.dev/wistia/apis/data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wistia/apis/data-api/revisions/b86cb2a7b420?raw)