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

```json
{
  "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`:

```json
{
  "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

```bash
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)

```json
{
  "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.

```bash
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.