> ## 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.

# Create Token

> Create a new design token

# Create Token

Creates a new design token in a specific mode.

<Note>
  **Write access policy** - This endpoint requires the `write:tokens` scope.

  * TEAM-owned workspace: `owner`, `admin`, `editor` can write; `viewer` is blocked (`403`).
  * Non-TEAM workspace: only the workspace owner can write.
  * If the workspace owner plan has no API write access (for example FREE), write is blocked.
</Note>

## Endpoint

```
POST /tokensets/{id}/modes/{modeId}/tokens
```

## Request

### Path Parameters

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id`      | string | Yes      | Tokenset ID |
| `modeId`  | string | Yes      | Mode ID     |

### Body Parameters

| Parameter     | Type   | Required      | Description                                           |
| ------------- | ------ | ------------- | ----------------------------------------------------- |
| `name`        | string | Yes           | Token name (dot notation, e.g., `colors.primary.500`) |
| `type`        | string | Yes           | Token type (see valid types below)                    |
| `value`       | string | Conditionally | Token value (required unless `alias_to` is provided)  |
| `description` | string | No            | Optional description                                  |
| `alias_to`    | string | No            | Reference to another token (for aliases)              |

### Valid 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
* `string` - String values
* `boolean` - Boolean values

## Response

**Status:** `201 Created`

```json theme={null}
{
  "id": "token-123",
  "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"
}
```

## Examples

<CodeGroup>
  ```bash Color Token theme={null}
  curl -X POST https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "colors.primary.500",
      "type": "color",
      "value": "#3b82f6",
      "description": "Primary brand color"
    }'
  ```

  ```bash Dimension Token theme={null}
  curl -X POST https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "spacing.base",
      "type": "dimension",
      "value": "16px",
      "description": "Base spacing unit"
    }'
  ```

  ```bash Alias Token theme={null}
  curl -X POST https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "button.primary.background",
      "type": "color",
      "alias_to": "colors.primary.500"
    }'
  ```

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

  // Create color token
  const colorToken = await fetch(
    `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes/${modeId}/tokens`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'colors.primary.500',
        type: 'color',
        value: '#3b82f6',
        description: 'Primary brand color'
      })
    }
  ).then(r => r.json());

  // Create alias token
  const aliasToken = await fetch(
    `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes/${modeId}/tokens`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'button.primary.background',
        type: 'color',
        alias_to: 'colors.primary.500'
      })
    }
  ).then(r => r.json());
  ```

  ```python Python theme={null}
  tokenset_id = 'tokenset-123'
  mode_id = 'mode-light'

  # Create color token
  color_token = requests.post(
      f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens',
      headers={
          'Authorization': 'Bearer tkc_your_token_here',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'colors.primary.500',
          'type': 'color',
          'value': '#3b82f6',
          'description': 'Primary brand color'
      }
  ).json()

  # Create spacing token
  spacing_token = requests.post(
      f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens',
      headers={
          'Authorization': 'Bearer tkc_your_token_here',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'spacing.base',
          'type': 'dimension',
          'value': '16px',
          'description': 'Base spacing unit'
      }
  ).json()
  ```
</CodeGroup>

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": "Name is required and must be a non-empty string"
}
```

```json theme={null}
{
  "error": "Type is required and must be one of: color, dimension, ..."
}
```

```json theme={null}
{
  "error": "Value is required and must be a string (unless alias_to is provided)"
}
```

### 404 Not Found

```json theme={null}
{
  "error": "Mode not found"
}
```

## Naming Convention

Use dot notation for hierarchical organization:

```
category.subcategory.property.variant
```

### Examples

✅ **Good:**

* `colors.primary.500`
* `spacing.component.padding.x`
* `font.size.heading.h1`

❌ **Bad:**

* `primaryColor500`
* `spacing_base`
* `fontSizeBody`

## Token Aliases

Create semantic tokens that reference base tokens:

```javascript theme={null}
// Base token
await createToken(tokensetId, modeId, {
  name: 'colors.blue.500',
  type: 'color',
  value: '#3b82f6'
});

// Semantic alias
await createToken(tokensetId, modeId, {
  name: 'button.primary.background',
  type: 'color',
  value: '',
  alias_to: 'colors.blue.500'
});
```

## Batch Creation

Create multiple tokens:

```javascript theme={null}
const tokens = [
  { name: 'colors.primary.400', type: 'color', value: '#60a5fa' },
  { name: 'colors.primary.500', type: 'color', value: '#3b82f6' },
  { name: 'colors.primary.600', type: 'color', value: '#2563eb' }
];

for (const token of tokens) {
  await createToken(tokensetId, modeId, token);
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Update Token" icon="pen" href="/api-reference/tokens/update">
    Update token details
  </Card>

  <Card title="List Tokens" icon="list" href="/api-reference/tokens/list">
    View all tokens
  </Card>
</CardGroup>