List Tokens

Get all tokens for a specific mode

List Tokens

Retrieves all design tokens for a specific mode within a tokenset.

Endpoint

GET /api/v1/tokensets/{id}/modes/{modeId}/tokens

Request

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Tokenset ID
modeId	string	Yes	Mode ID

Response

Status: 200 OK

{
  "mode": {
    "id": "mode-light",
    "name": "Light",
    "is_default": true
  },
  "tokens": [
    {
      "id": "token-1",
      "tokenset_id": "tokenset-123",
      "mode_id": "mode-light",
      "name": "colors.primary.500",
      "type": "color",
      "value": "#3b82f6",
      "description": "Primary brand color",
      "alias_to": null,
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z"
    },
    {
      "id": "token-2",
      "tokenset_id": "tokenset-123",
      "mode_id": "mode-light",
      "name": "spacing.base",
      "type": "dimension",
      "value": "16px",
      "description": "Base spacing unit",
      "alias_to": null,
      "created_at": "2025-01-15T10:10:00Z",
      "updated_at": "2025-01-15T10:10:00Z"
    }
  ],
  "total": 2
}

Token Object

Field	Type	Description
id	string	Unique token identifier
tokenset_id	string	Parent tokenset ID
mode_id	string	Parent mode ID
name	string	Token name (dot notation)
type	string	Token type (color, dimension, etc.)
value	any	Token value
description	string|null	Optional description
alias_to	string|null	Reference to another token
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Supported Token Types

• color - Color values
• dimension - Sizes and spacing
• fontFamily - Font families
• fontWeight - Font weights
• fontSize - Font sizes
• lineHeight - Line heights
• letterSpacing - Letter spacing
• duration - Animation durations
• cubicBezier - Easing functions
• number - Numeric values
• strokeStyle - Stroke styles
• border - Border definitions
• transition - Transition definitions
• shadow - Shadow effects
• gradient - Gradient definitions
• typography - Complete typography definitions

Examples

cURL

curl -H "Authorization: Bearer dtk_your_token_here" \
  https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens

Use Cases

1. Display Token List

Show all tokens in a UI:

function TokenList({ tokens }) {
  return (
    <div>
      {tokens.map(token => (
        <div key={token.id}>
          <h3>{token.name}</h3>
          <p>{token.type}: {token.value}</p>
          {token.description && <p>{token.description}</p>}
        </div>
      ))}
    </div>
  );
}

2. Generate Documentation

Create auto-generated docs:

async function generateDocs(tokensetId, modeId) {
  const { tokens } = await getTokens(tokensetId, modeId);
  
  const byCategory = tokens.reduce((acc, token) => {
    const [category] = token.name.split('.');
    if (!acc[category]) acc[category] = [];
    acc[category].push(token);
    return acc;
  }, {});
  
  return Object.entries(byCategory).map(([category, tokens]) => ({
    category,
    tokens
  }));
}

3. Search Tokens

Filter by name or type:

async function searchTokens(tokensetId, modeId, query) {
  const { tokens } = await getTokens(tokensetId, modeId);
  
  return tokens.filter(token =>
    token.name.toLowerCase().includes(query.toLowerCase()) ||
    token.description?.toLowerCase().includes(query.toLowerCase())
  );
}

Next Steps

Get Specific Token

Get a single token by name

Export Tokens

Export in multiple formats