Create Brand Kit
Create a brand kit — from a URL (extraction) or from direct fields (manual).
Pass url to run server-side extraction of brand info from a website,
OR pass name (with optional colors / fonts / logo_file_ids)
to build a kit manually — the same write the web app’s manual onboarding
performs, for brands without a website. Exactly one of the two paths per
request (enforced by the request schema).
Honors idempotency_key through the shared pipeline (a keyed retry
replays the stored result instead of minting a duplicate kit). A stored
result whose kit was DELETED since does not replay: the stale record is
invalidated and the create re-executes fresh (loud
stale_replay_invalidated marker). Brand create is NOT metered on
either path — no billing runs here — so the response carries the
zero-credit deterministic usage receipt.
Authorizations
API key from Settings > Developer > REST API
Headers
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.
2026-04-12, 2026-05-01 "2026-05-01"
Body
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.
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).
Display name for a manually-built kit (also stored as the kit's company_name). Required for the manual path; mutually exclusive with url.
1 - 255Manual 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.
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.
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.
20Prefixed 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.
^file_[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$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.
200Response
Successful Response
The response is of type Response Createbrandkit · object.