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

# List Tokens

> Get all tokens for a specific mode

# List Tokens

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

## Endpoint

```
GET /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`

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer tkc_your_token_here" \
    https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens
  ```

  ```javascript JavaScript theme={null}
  const tokensetId = 'tokenset-123';
  const modeId = 'mode-light';

  const response = await fetch(
    `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes/${modeId}/tokens`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TOKENCRAFT_TOKEN}`
      }
    }
  );

  const { tokens } = await response.json();

  // Filter by type
  const colors = tokens.filter(t => t.type === 'color');
  const spacing = tokens.filter(t => t.type === 'dimension');

  console.log(`Found ${colors.length} colors and ${spacing.length} dimensions`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens',
      headers={'Authorization': f'Bearer {token}'}
  )

  data = response.json()
  tokens = data['tokens']

  # Group by type
  from collections import defaultdict
  by_type = defaultdict(list)

  for token in tokens:
      by_type[token['type']].append(token)

  print(f"Colors: {len(by_type['color'])}")
  print(f"Spacing: {len(by_type['dimension'])}")
  ```
</CodeGroup>

## Use Cases

### 1. Display Token List

Show all tokens in a UI:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Get Specific Token" icon="circle" href="/api-reference/tokens/get">
    Get a single token by name
  </Card>

  <Card title="Export Tokens" icon="file-export" href="/api-reference/export/mode">
    Export in multiple formats
  </Card>
</CardGroup>