API · BrandKit · Populate a brand kit (canonical schema)
Submit a canonical BrandKitDocument body to populate a brand kit. Every top-level section is optional, allowing incremental calls:
brand— name, description, website URLsocial_links— array of {type, url} objectsstyle— full visual-identity JSON (colors, typography, logos, imagery, logo_lockup, on_image_copy, ai_guardrails, prose, inferred_fields)- Row sections, each merged by normalized name or title with omitted rows
preserved:
features(1–20),icps(1–5),content_pillars(1–5),usps(1–10),competitor_analysis(1–10). Each section is named by the context-document key it is read back as. These are the only write path for those documents; never write them as context documents. An unknown section name is a 400 that lists the valid ones.
The body shape is identical to the GET response (without id). Empty body {}
is a valid no-op. Server-controlled fields (id, version) in the body are ignored.
Runs synchronously and returns 200 with the result. Calling this endpoint multiple
times is safe — sections sent overwrite their own fields; omitted sections are left
unchanged. Do NOT call getTaskResult after this — there is no async task; the
operation is complete by the time the response returns.
Authentication
Header authentication of the form Api-Key <token>
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Request
Handle returned by web_brand_extract (as the _extract_ref field).
When set, the agent runtime fetches the cached extraction and fills
missing brand (description, website — never name, which is the
kit title set at create), social_links, and the mechanical parts
of style: colors, typography, logos, and every
assets.reference_images entry the crawler kept. Explicit fields
on the request override the inflated values. The agent authors
only the judgement fields of style (imagery, ai_guardrails,
prose). An expired or unknown handle (extracts live 15 minutes)
is a tool error — re-run web_brand_extract for a fresh one.
This field is consumed by the apikit pre-hook and is never
forwarded to the API itself.
Set when the user declined to supply required brand facts during onboarding, so the agent stops re-asking and shows a soft reminder instead. ISO8601 UTC. A lifecycle marker on the kit, not brand data.
Canonical ideal-customer profiles grounded during onboarding.
Supplying this section creates or updates ICPs by case-insensitive
title and preserves existing ICPs omitted from the request. Titles
must be unique and at most one item may set is_primary to true.
Omit the section to leave all ICPs unchanged; deletion remains an
explicit action in the Brand Kit UI or ICP CRUD API.
Canonical content themes grounded during onboarding. Supplying this section creates or updates pillars by case-insensitive name and preserves existing pillars omitted from the request. Omit the section to leave all pillars unchanged; deletion remains an explicit action in the Brand Kit UI or pillar CRUD API.
What the brand sells, as canonical product rows — the rows behind
the features context document. Supplying this section creates or
updates rows by case-insensitive name and preserves existing rows
omitted from the request. Names must be unique. Omit the section to
leave all rows unchanged; deletion remains an explicit action in the
Brand Kit UI or product CRUD API.
target_icps names existing ICPs by title; unknown titles are
ignored, never created.
Unique selling points as canonical rows — the source of the usps
context document. Supplying this section creates or updates USPs by
case-insensitive title and preserves existing USPs omitted from the
request. Titles must be unique and at most one item may set
is_primary to true (it replaces the previous primary). Omit the
section to leave all USPs unchanged.
Competitors as canonical rows — the rows behind the
competitor_analysis context document (the narrative document, when
one exists, is appended to the rendered read). Supplying this
section creates or updates competitors by case-insensitive name and
preserves existing competitors omitted from the request. Names must
be unique. Omit the section to leave all competitors unchanged.
Visual identity sub-document. Versioned independently via schema_version.
Sub-fields permit unknown keys for forward-compat (motion tokens, dark-mode palette, etc.)
Response
Stamped envelope version (always 2 after a V2 build)
Non-fatal warnings from sub-steps (e.g. style_guide render)
