Skip to main content
POST
Create Brand Kit

Authorizations

Authorization
string
header
required

API key from Settings > Developer > REST API

Headers

Moda-Version
enum<string>
default:2026-05-01

Calendar-dated API version pin. New integrations should pin 2026-05-01 to opt into the newest response shapes. For back-compat the server also accepts requests with no header and resolves them to the current default (today: 2026-04-12); that default advances on each sunset date. Any unsupported value returns 400 unsupported_version.

Available options:
2026-04-12,
2026-05-01
Example:

"2026-05-01"

Body

application/json

Request body for POST /v1/brand-kits — two mutually exclusive creation paths.

Extraction (url): server-side extraction of colors, fonts, and logos from a live website. Manual (name + optional colors / fonts / logo_file_ids): build the kit from directly-supplied fields — for brands with no website, or when the caller already holds the ground truth. Exactly one of url or name must be provided.

url
string | null

Company website URL or domain (e.g. 'stripe.com') to extract brand data from. Mutually exclusive with the manual fields (name / colors / fonts / logo_file_ids).

name
string | null

Display name for a manually-built kit (also stored as the kit's company_name). Required for the manual path; mutually exclusive with url.

Required string length: 1 - 255
colors
Colors · object[] | null

Manual path only: initial palette as an array of {color, label?, mode?, gradient?} objects (color is a hex string, e.g. '#0F172A'; mode is 'light' / 'dark' / 'any'). Same shape as the PATCH colors field.

fonts
Fonts · object[] | null

Manual path only: initial fonts as an array of {family, label?, weight?} objects. Same shape as the PATCH fonts field. Each font's supported flag is derived server-side from the platform + team font catalogs; a caller-supplied value is ignored.

logo_file_ids
string[] | null

Manual path only: file_ IDs (from POST /v1/uploads) to attach as logos. Files must be images (image/*). Equivalent to calling addBrandKitImage with role='logo' for each after create, but atomic with the create itself.

Maximum array length: 20

Prefixed file_ wire ID (Crockford base32 body) — the canonical, recommended form. For back-compat, a bare UUID string is also accepted in both path parameters and JSON request bodies (older integrations that stored raw UUIDs keep working). Both are permanent, supported inputs.

Pattern: ^file_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$
idempotency_key
string | null

A retried create with the same key replays the stored result (replayed: true) instead of creating a second brand kit. Same-key reuse with a different payload is a 409 idempotency_conflict.

Maximum string length: 200

Response

Successful Response

The response is of type Response Createbrandkit · object.