Tokens

List tokens

string

Filter by token type (e.g., color, spacing, font.size).

string

default:"flat"

Response format: flat (array) or nested (object tree).

curl https://humic.dev/api/v1/tokens \
  -H "Authorization: Bearer sk_live_your_key"

Flat response (default)

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

curl "https://humic.dev/api/v1/tokens?format=nested" \
  -H "Authorization: Bearer sk_live_your_key"

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

Names that are also groups

A token can be named after a group of other tokens — color.brand alongside color.brand.hover. In the tree, color.brand has to be both a value and a group, so its value moves one level down into the reserved $root key (W3C DTCG §6.1), exactly as the DTCG export does:

{
  "color": {
    "brand": {
      "$root": { "type": "color", "value": { "scale": "brand", "step": 500 } },
      "hover": { "type": "color", "value": { "scale": "brand", "step": 600 } }
    }
  }
}

Read {group}.$root as the token named {group}. Only names that are actually shadowed move — a group with no token of its own never gets a $root key. The flat format is unaffected: it keeps the token’s real name.

total counts the tokens present in the response body. In the nested format that can be lower than the number of tokens in the design system, since a name that cannot be expressed as an object key is omitted from the tree.

Get a single token

Retrieve a token by name using path segments:

curl https://humic.dev/api/v1/tokens/color/brand/primary \
  -H "Authorization: Bearer sk_live_your_key"

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

// 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" }

Getting Started

API Reference

Export Formats

Integrations

List tokens

Flat response (default)

Nested response

Names that are also groups

Get a single token

Token value shapes

​List tokens

​Flat response (default)

​Nested response

​Names that are also groups

​Get a single token

​Token value shapes

List tokens

Flat response (default)

Nested response

Names that are also groups

Get a single token

Token value shapes