> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens

> Read design tokens via the Humic API.

## List tokens

<ParamField query="type" type="string" optional>
  Filter by token type (e.g., `color`, `spacing`, `font.size`).
</ParamField>

<ParamField query="format" type="string" optional default="flat">
  Response format: `flat` (array) or `nested` (object tree).
</ParamField>

```bash theme={null}
curl https://humic.dev/api/v1/tokens \
  -H "Authorization: Bearer sk_live_your_key"
```

### Flat response (default)

```json theme={null}
{
  "data": {
    "tokens": [
      {
        "key": "color.brand.primary",
        "type": "color",
        "value": { "scale": "brand", "step": 500 }
      },
      {
        "key": "spacing.page.gutter",
        "type": "spacing",
        "value": { "value": 16, "unit": "px" }
      }
    ],
    "total": 42
  }
}
```

### Nested response

```bash theme={null}
curl "https://humic.dev/api/v1/tokens?format=nested" \
  -H "Authorization: Bearer sk_live_your_key"
```

```json theme={null}
{
  "data": {
    "tokens": {
      "color": {
        "brand": {
          "primary": {
            "type": "color",
            "value": { "scale": "brand", "step": 500 }
          }
        }
      },
      "spacing": {
        "page": {
          "gutter": {
            "type": "spacing",
            "value": { "value": 16, "unit": "px" }
          }
        }
      }
    },
    "total": 42
  }
}
```

## Get a single token

Retrieve a token by name using path segments:

```bash theme={null}
curl https://humic.dev/api/v1/tokens/color/brand/primary \
  -H "Authorization: Bearer sk_live_your_key"
```

```json theme={null}
{
  "data": {
    "key": "color.brand.primary",
    "type": "color",
    "value": { "scale": "brand", "step": 500 }
  }
}
```

Returns `404` if the token does not exist.

## Token value shapes

Each token type has a specific value structure:

```json theme={null}
// color — references a scale + step
{ "scale": "brand", "step": 500, "darkStep": 400 }

// spacing, radius, font.size
{ "value": 16, "unit": "px" }

// font.weight
{ "value": 700 }

// font.family
{ "value": "Inter" }

// font.lineHeight
{ "value": 1.25, "unit": "multiplier" }

// font.letterSpacing
{ "value": 0.025, "unit": "em" }

// shadow
{ "x": 0, "y": 1, "blur": 3, "spread": 0, "colorToken": "color.shadow", "opacity": 0.1 }

// opacity, z-index, duration
{ "value": 0.5 }

// easing
{ "value": "cubic-bezier(0.16, 1, 0.3, 1)" }

// boolean
{ "value": true }

// primitive reference (any non-color type)
{ "primitive": "spacing.md" }
```