---
title: Brand
kind: resource
slug: brand
summary: "The canonical Hi Marley brand — design tokens, expression assets, skills, voice & guidelines, and a downloadable kit. Built for humans and machines."
---

# Brand

The canonical Hi Marley brand — design tokens, expression assets, skills, voice & guidelines, and a downloadable kit. Built for humans and machines.

The **Brand** is the single source of truth for what "on-brand" means at Hi Marley — for people building decks and droplets, and for agents generating content. It exposes machine-readable design **tokens** (`/api/brand/tokens.json`), the curated **expression assets** (photography, iconography, patterns, network expression), the brand **skills**, and the **voice & guidelines**.

Access is gated to **Brand Stewards** (`@drop-brand-stewards`) while the new brand is in progress. Customer logos, employee headshots, and other "handy" assets live in the [Library](/docs/resources/library), separately — the Brand and Library sit side by side.

There is no versioning: one canonical brand, no draft/archived states.

### Icon tiers

Iconography carries a **curation tier**, separate from tags. Tags describe what an asset is *about* (`lifestyle`, `business`, `ai`); tier describes how prominent it is:

- `marquee` — the named, hand-curated set. The website nav icons and the ecosystem chips, in a deliberate order (`tierRank`).
- `common` — frequently used, one step below the marquee set.
- `library` — everything else. The default, and the bulk of the ~5,000 icons.

**If you are an agent picking an icon, start with `--tier marquee`.** It is the small set Hi Marley actually uses, so it is the on-brand answer far more often than a name search across the full library. Widen to `common`, then drop the tier filter entirely, only if nothing fits. Search without a tier reaches every tier.

## The Brand object

### Attributes

- **`name`** `string` — Display name of the brand.
- **`tagline`** `string` — One-line description shown in the Brand OS header.
- **`assetCount`** `integer` — Total brand expression assets across all categories.
- **`skillCount`** `integer` — Number of brand skills linked to the brand.
- **`assetTier`** `'marquee' | 'common' | 'library'` — Curation tier on an iconography asset — how prominent it is, separate from `tags` (which describe subject matter). Defaults to `library`. Filter with `--tier` on `brand assets list` / `search`; set with `brand assets update --tier` or `brand assets bulk-tier`. `tierRank` orders the marquee set.
- **`colorTokenCount`** `integer` — Number of color tokens in the palette (Core + Supporting tiers). Each token carries its full build — hex, and optionally PMS/CMYK/RGB and a `--marley-*` cssVar cross-ref. Read via `/api/brand/tokens.json`; stewards edit them in the Basics tab.

### JSON example

```json
{
  "name": "Hi Marley Brand",
  "tagline": "Everything you need to be on-brand — for humans and machines.",
  "assetCount": 175,
  "skillCount": 3,
  "colorTokenCount": 9
}
```

## Methods

### Get brand tokens

`GET /api/brand/tokens.json`

Return the machine-readable design tokens — color palette and typeface. This is the endpoint agents and build tools pull so they never guess brand values. Brand Steward access required.

**CLI**

```bash
drop brand tokens
```

**MCP**

```json
{
  "tool": "drop_brand_tokens_get",
  "arguments": {}
}
```

**HTTP**

```bash
curl -X GET 'https://drop.himarley.ai/api/brand/tokens.json' \
  -H "Authorization: Bearer $DROP_TOKEN"
```

**Response** (200)

```json
{
  "colors": [
    {
      "tier": "core",
      "name": "Marley Red",
      "hex": "#F9685D",
      "pms": "7416 C",
      "cmyk": "0 74 60 0",
      "rgb": "249 104 93",
      "cssVar": "--marley-coral",
      "usage": "Primary actions, CTAs"
    }
  ],
  "typeface": {
    "name": "Greycliff CF",
    "role": "Display & headings"
  }
}
```

### List brand assets

`GET /api/brand/assets`

List the brand expression assets — photography, iconography, patterns, network expression. Optionally filter by category or curation tier (`marquee` = the named, hand-curated set; `common` = frequently used; `library` = everything else). Brand Steward access required.

**CLI**

```bash
drop brand assets list --category icon
```

**MCP**

```json
{
  "tool": "drop_brand_assets_list",
  "arguments": {
    "category": "icon"
  }
}
```

**HTTP**

```bash
curl -X GET 'https://drop.himarley.ai/api/brand/assets' \
  -H "Authorization: Bearer $DROP_TOKEN"
```

**Response** (200)

```json
{
  "assets": [
    {
      "id": "i1",
      "filename": "icon_handshake_outline_red.svg",
      "category": "icon",
      "url": "https://drop-apps.himarley.xyz/_library/brand/assets/.../icon_handshake_outline_red.svg"
    }
  ]
}
```

### Update a brand asset

`PATCH /api/brand/assets/{id}`

Edit a brand asset’s metadata (tags, usage guidance, alt text) or retire/restore it (`archived`). Metadata edits never change the asset’s URL. To change the artwork itself, upload a new asset instead — URLs are immutable so existing references never silently move. Brand Steward access required.

**Parameters**

- **`id`** _(string · path · required)_ — The brand asset id.
- **`tags`** _(string[] · body)_ — Replace the tag set.
- **`usageGuidance`** _(string | null · body)_ — AI usage guidance; null to clear.
- **`altText`** _(string | null · body)_ — Alt text; null to clear.
- **`archived`** _(boolean · body)_ — true to retire, false to restore.
- **`tier`** _('marquee' | 'common' | 'library' · body)_ — Curation tier.
- **`tierRank`** _(number | null · body)_ — Order within the marquee set; null to unrank.

**CLI**

```bash
drop brand assets update ckbrandasset0001 --usage-guidance "Use on dark backgrounds only."
```

**MCP**

```json
{
  "tool": "drop_brand_assets_update",
  "arguments": {
    "id": "ckbrandasset0001",
    "usageGuidance": "Use on dark backgrounds only.",
    "archived": false
  }
}
```

**HTTP**

```bash
curl -X PATCH 'https://drop.himarley.ai/api/brand/assets/ckbrandasset0001' \
  -H "Authorization: Bearer $DROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"usageGuidance":"Use on dark backgrounds only.","archived":false}'
```

**Response** (200)

```json
{
  "asset": {
    "id": "ckbrandasset0001",
    "filename": "logo_hi_marley_white.svg",
    "category": "logo",
    "url": "https://drop-apps.himarley.xyz/_brand/assets/.../logo_hi_marley_white.svg",
    "tags": [],
    "usageGuidance": "Use on dark backgrounds only.",
    "altText": null,
    "archivedAt": null
  }
}
```

### Delete a brand asset

`DELETE /api/brand/assets/{id}`

Permanently delete a brand asset — removes the database row and the underlying S3 object. This breaks any URL that still points at it, so reserve it for mistakes; to retire a published asset safely, use `brand assets update --archived` instead. Brand Steward access required.

**Parameters**

- **`id`** _(string · path · required)_ — The brand asset id.

**CLI**

```bash
drop brand assets delete ckbrandasset0001
```

**MCP**

```json
{
  "tool": "drop_brand_assets_delete",
  "arguments": {
    "id": "ckbrandasset0001"
  }
}
```

**HTTP**

```bash
curl -X DELETE 'https://drop.himarley.ai/api/brand/assets/ckbrandasset0001' \
  -H "Authorization: Bearer $DROP_TOKEN"
```

**Response** (200)

```json
{
  "deleted": true,
  "id": "ckbrandasset0001"
}
```

### Search brand assets

`GET /api/brand/assets/search`

Find brand assets by free-text query (matched across filename, tags, usage guidance, and alt text) with optional category and tag filters. Built for agents choosing the right asset for a use case — tag your assets well and this becomes the lookup. Brand Steward access required.

**Parameters**

- **`q`** _(string · query)_ — Free-text query (AND across filename/tags/usage/alt).
- **`category`** _(enum · query)_ — photo | icon | pattern | logo | font.
- **`tag`** _(string · query)_ — Require this exact asset tag.
- **`includeArchived`** _(boolean · query)_ — Include retired assets (default false).
- **`limit`** _(number · query)_ — Cap results (max 200).

**CLI**

```bash
drop brand assets search --q handshake --category icon
```

**MCP**

```json
{
  "tool": "drop_brand_assets_search",
  "arguments": {
    "q": "handshake",
    "category": "icon"
  }
}
```

**HTTP**

```bash
curl -X GET 'https://drop.himarley.ai/api/brand/assets/search' \
  -H "Authorization: Bearer $DROP_TOKEN"
```

**Response** (200)

```json
{
  "assets": [
    {
      "id": "ck1",
      "filename": "icon_handshake_outline_red.svg",
      "category": "icon",
      "url": "https://drop-apps.himarley.xyz/_brand/assets/.../icon_handshake_outline_red.svg",
      "tags": [
        "partnership",
        "agreement"
      ],
      "usageGuidance": "Use for partnership/agreement moments.",
      "altText": null,
      "archivedAt": null
    }
  ]
}
```

### List brand asset tags

`GET /api/brand/assets/tags`

List the brand-asset tag vocabulary — the distinct tags stewards have applied to assets, with usage counts, ranked by frequency. These are a separate namespace from droplet tags. Optional `q` filters by substring. Brand Steward access required.

**Parameters**

- **`q`** _(string · query)_ — Filter tags by substring.

**CLI**

```bash
drop brand assets tags
```

**MCP**

```json
{
  "tool": "drop_brand_assets_tags",
  "arguments": {}
}
```

**HTTP**

```bash
curl -X GET 'https://drop.himarley.ai/api/brand/assets/tags' \
  -H "Authorization: Bearer $DROP_TOKEN"
```

**Response** (200)

```json
{
  "tags": [
    {
      "tag": "partnership",
      "count": 4,
      "lastUsed": "2026-07-01T12:00:00.000Z"
    }
  ]
}
```

### Bulk add/remove asset tags

`POST /api/brand/assets/bulk/tags`

Add and/or remove tags across many brand assets at once (union-add then set-remove, normalized + deduped per asset). Powers multi-select tagging. Ids not on the canonical brand are returned in `notFound`. Brand Steward access required.

**Parameters**

- **`ids`** _(string[] · body · required)_ — Asset ids to tag (1-200).
- **`add`** _(string[] · body)_ — Tags to add (union).
- **`remove`** _(string[] · body)_ — Tags to remove.

**CLI**

```bash
drop brand assets bulk-tags --ids ck1,ck2 --add partnership --remove draft
```

**MCP**

```json
{
  "tool": "drop_brand_assets_bulk_tags",
  "arguments": {
    "ids": [
      "ck1",
      "ck2"
    ],
    "add": [
      "partnership"
    ],
    "remove": [
      "draft"
    ]
  }
}
```

**HTTP**

```bash
curl -X POST 'https://drop.himarley.ai/api/brand/assets/bulk/tags' \
  -H "Authorization: Bearer $DROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["ck1","ck2"],"add":["partnership"],"remove":["draft"]}'
```

**Response** (200)

```json
{
  "updated": [
    {
      "id": "ck1",
      "tags": [
        "partnership"
      ]
    },
    {
      "id": "ck2",
      "tags": [
        "partnership"
      ]
    }
  ],
  "notFound": []
}
```

### Bulk set asset curation tier

`POST /api/brand/assets/bulk/tier`

Set the curation tier across many brand assets at once. Every found id reports the tier it now holds, whether or not it changed; ids not on the canonical brand come back in `notFound`. To order icons within the marquee set, use `brand assets update --tier-rank`. Brand Steward access required.

**Parameters**

- **`ids`** _(string[] · body · required)_ — Asset ids to retier (1-200).
- **`tier`** _('marquee' | 'common' | 'library' · body · required)_ — The tier to set.

**CLI**

```bash
drop brand assets bulk-tier --ids ck1,ck2 --tier common
```

**MCP**

```json
{
  "tool": "drop_brand_assets_bulk_tier",
  "arguments": {
    "ids": [
      "ck1",
      "ck2"
    ],
    "tier": "common"
  }
}
```

**HTTP**

```bash
curl -X POST 'https://drop.himarley.ai/api/brand/assets/bulk/tier' \
  -H "Authorization: Bearer $DROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["ck1","ck2"],"tier":"common"}'
```

**Response** (200)

```json
{
  "updated": [
    {
      "id": "ck1",
      "tier": "common"
    },
    {
      "id": "ck2",
      "tier": "common"
    }
  ],
  "notFound": []
}
```