Skip to navigation
PlatformBrand Kits

API · BrandKit · Populate a brand kit (canonical schema)

View as Markdown

Submit a canonical BrandKitDocument body to populate a brand kit. The body has four top-level sections — all optional, allowing incremental calls:

  • brand — name, description, website URL
  • social_links — array of {type, url} objects
  • content_pillars — 1–5 grounded themes, merged by normalized name
  • style — full visual-identity JSON (colors, typography, logos, imagery, logo_lockup, on_image_copy, ai_guardrails, prose, inferred_fields)

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. Content pillars omitted from a supplied list are preserved. Do NOT call getTaskResult after this — there is no async task; the operation is complete by the time the response returns.

Authentication

AuthorizationApi-Key

Header authentication of the form Api-Key <token>

OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

brand_idstringRequiredformat: "uuid"
Brand kit UUID

Request

This endpoint expects an object.
extract_refstringOptional

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.

brandobject or nullOptional
Core brand identity.
icpslist of objects or nullOptional

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.

content_pillarslist of objects or nullOptional

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.

styleobject or nullOptional

Visual identity sub-document. Versioned independently via schema_version. Sub-fields permit unknown keys for forward-compat (motion tokens, dark-mode palette, etc.)

Response

Build complete. Operation finished synchronously.
brand_kit_idstringOptionalformat: "uuid"
statusstringOptional
ok
versionintegerOptional

Stamped envelope version (always 2 after a V2 build)

warningslist of stringsOptional

Non-fatal warnings from sub-steps (e.g. style_guide render)

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error