Brand Kit API

REST API endpoints for managing your store's brand kit, guidelines, and design tokens.

The Brand Kit API lets you store and retrieve structured brand information — colors, typography, logos, voice, and imagery — plus free-form markdown guidelines. This data powers the AI Builder's design decisions and can be consumed by any integration that needs your brand's source of truth.

Get Brand Kit

GET /api/v1/brand-kit

Returns the store's brand kit, guidelines, source PDF URL, and last-updated timestamp. Fields are null when no brand kit has been configured.

Response

{
  "brandKit": {
    "name": "Acme Store",
    "tagline": "Quality goods, delivered fast",
    "colors": [
      { "name": "Primary", "hex": "#1a73e8", "role": "primary" },
      { "name": "Accent", "hex": "#ff6d00", "role": "accent" }
    ],
    "typography": {
      "headingFont": "Inter",
      "bodyFont": "Source Sans Pro",
      "scale": "normal"
    },
    "logos": [
      {
        "variant": "primary",
        "url": "https://cdn.example.com/logo.png",
        "background": "light"
      }
    ],
    "voice": {
      "tone": ["confident", "friendly"],
      "personality": "Approachable yet professional",
      "dos": ["Use active voice", "Be concise"],
      "donts": ["Avoid jargon", "No all-caps"]
    },
    "imagery": {
      "style": "Minimal lifestyle photography",
      "subjects": ["product in use", "flat lay"],
      "avoid": ["stock photos", "cluttered backgrounds"]
    },
    "borderRadius": "md"
  },
  "guidelines": "## Logo Usage\n\nAlways maintain 24px clearspace around the logo...",
  "pdfUrl": "https://example.com/brand-guide.pdf",
  "updatedAt": "2026-04-23T12:00:00.000Z"
}

When no brand kit exists, all top-level fields are null:

{
  "brandKit": null,
  "guidelines": null,
  "pdfUrl": null,
  "updatedAt": null
}

Update Brand Kit

PUT /api/v1/brand-kit

Partial update — omitted top-level fields are left unchanged. Send null to clear a field.

Request Body

Field	Type	Required	Description
`brandKit`	`object \| null`	No	Structured brand fields (see schema below). `null` clears the kit.
`guidelines`	`string \| null`	No	Free-form markdown guidelines (max 50,000 characters). `null` clears.
`pdfUrl`	`string \| null`	No	URL to the source brand PDF. `null` clears.

Brand Kit Object

Field	Type	Description
`name`	`string`	Brand name as it should appear
`tagline`	`string`	Short tagline or positioning line
`mission`	`string`	Mission or value proposition
`audience`	`string`	Target audience description
`colors`	`Color[]`	Brand colors (see below)
`typography`	`object`	Typography settings (see below)
`logos`	`Logo[]`	Logo variants (see below)
`voice`	`object`	Brand voice and tone (see below)
`imagery`	`object`	Imagery and photography guidelines (see below)
`borderRadius`	`string`	Corner radius preference: `none`, `sm`, `md`, `lg`, `full`
`links`	`object`	Social and website links: `website`, `instagram`, `twitter`, `linkedin`

All fields are optional. Only include what you want to set or update.

Color Object

Field	Type	Required	Description
`name`	`string`	Yes	Label (e.g. "Primary", "Accent")
`hex`	`string`	Yes	Hex color (e.g. `#1a73e8`)
`role`	`string`	No	Semantic role: `primary`, `secondary`, `accent`, `background`, `foreground`, `muted`, `border`, `other`
`notes`	`string`	No	Usage notes (e.g. "headings only")

Typography Object

Field	Type	Description
`headingFont`	`string`	Font family for headings
`bodyFont`	`string`	Font family for body text
`monoFont`	`string`	Font family for monospace/code
`fontUrls`	`string[]`	Direct font CDN URLs (Google Fonts, Fontshare, etc.)
`scale`	`string`	Type scale density: `compact`, `normal`, `spacious`
`notes`	`string`	Additional typography notes

Logo Object

Field	Type	Required	Description
`variant`	`string`	Yes	Logo variant: `primary`, `wordmark`, `mark`, `light`, `dark`, `monochrome`
`url`	`string`	Yes	Publicly accessible image URL
`background`	`string`	No	Intended background: `light`, `dark`, `any`

Voice Object

Field	Type	Description
`tone`	`string[]`	Tone descriptors (e.g. `["confident", "playful"]`)
`personality`	`string`	1-2 sentence personality summary
`dos`	`string[]`	Phrases/behaviors to embrace
`donts`	`string[]`	Phrases/behaviors to avoid
`vocabulary`	`object`	`{ preferred: string[], avoid: string[] }`

Imagery Object

Field	Type	Description
`style`	`string`	Photography/illustration style
`subjects`	`string[]`	What to depict
`avoid`	`string[]`	What never to depict
`referenceUrls`	`string[]`	Moodboard reference image URLs

Example Request

curl -X PUT \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "brandKit": {
      "name": "Acme Store",
      "colors": [
        { "name": "Primary", "hex": "#1a73e8", "role": "primary" },
        { "name": "Accent", "hex": "#ff6d00", "role": "accent" }
      ],
      "typography": {
        "headingFont": "Inter",
        "bodyFont": "Source Sans Pro"
      },
      "borderRadius": "md"
    },
    "guidelines": "Always use the primary color for CTAs."
  }' \
  https://your-store.yns.store/api/v1/brand-kit

Response (200)

Returns the full updated brand kit in the same shape as the GET response.

Error Response (400)

{
  "error": "Invalid request data",
  "details": [
    {
      "path": ["brandKit", "colors", 0, "hex"],
      "message": "Must be a hex color like #ff00aa"
    }
  ]
}

Delete Brand Kit

DELETE /api/v1/brand-kit

Clears the structured kit, guidelines, and source PDF reference. Returns no body.

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/brand-kit

Response

204 No Content — brand kit cleared.

PreviousImagesAPI Reference