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

> Create a new mode in a tokenset

# Create Mode

Creates a new mode (theme variation) within a tokenset.

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

## Authentication

Requires a valid API token in the Authorization header.

## Request

### Headers

| Header          | Value            | Required |
| --------------- | ---------------- | -------- |
| `Authorization` | Bearer token     | Yes      |
| `Content-Type`  | application/json | Yes      |

### Path Parameters

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

### Body Parameters

| Parameter    | Type    | Required | Description                                       |
| ------------ | ------- | -------- | ------------------------------------------------- |
| `name`       | string  | Yes      | Mode name (max 255 characters)                    |
| `is_default` | boolean | No       | Whether this mode is the default (default: false) |

<Note>
  If `is_default` is true, all other modes in this tokenset will be set to non-default.
</Note>

### Request Body

```json theme={null}
{
  "name": "Dark",
  "is_default": false
}
```

## Response

### Success Response

**Status:** `201 Created`

```json theme={null}
{
  "id": "mode-dark",
  "tokenset_id": "tokenset-123",
  "name": "Dark",
  "is_default": false,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}
```

## Examples

<CodeGroup>
  ```bash Create Default Mode theme={null}
  curl -X POST https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Light",
      "is_default": true
    }'
  ```

  ```bash Create Regular Mode theme={null}
  curl -X POST https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Dark"
    }'
  ```

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

  // Create light mode as default
  const lightMode = await fetch(
    `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Light',
        is_default: true
      })
    }
  ).then(r => r.json());

  // Create dark mode
  const darkMode = await fetch(
    `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Dark',
        is_default: false
      })
    }
  ).then(r => r.json());
  ```

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

  # Create light mode as default
  light_mode = requests.post(
      f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes',
      headers={
          'Authorization': 'Bearer tkc_your_token_here',
          'Content-Type': 'application/json'
      },
      json={'name': 'Light', 'is_default': True}
  ).json()

  # Create dark mode
  dark_mode = requests.post(
      f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes',
      headers={
          'Authorization': 'Bearer tkc_your_token_here',
          'Content-Type': 'application/json'
      },
      json={'name': 'Dark', 'is_default': False}
  ).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": "is_default must be a boolean"
}
```

### 404 Not Found

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

## Common Mode Names

### Theme Variations

* Light
* Dark
* High Contrast

### Platform Variations

* Web
* Mobile
* Desktop

### Brand Variations

* Primary Brand
* Secondary Brand

### Context Variations

* Marketing
* Product
* Admin

## Use Cases

### 1. Create Light/Dark Themes

```javascript theme={null}
async function setupThemes(tokensetId) {
  const light = await createMode(tokensetId, {
    name: 'Light',
    is_default: true
  });
  
  const dark = await createMode(tokensetId, {
    name: 'Dark'
  });
  
  return { light, dark };
}
```

### 2. Create Multi-Platform Modes

```javascript theme={null}
const platforms = ['Web', 'iOS', 'Android'];

for (const platform of platforms) {
  await createMode(tokensetId, {
    name: platform,
    is_default: platform === 'Web'
  });
}
```

## Default Mode Behavior

When setting a mode as default:

1. The new mode's `is_default` is set to `true`
2. All other modes in the tokenset are set to `is_default: false`
3. Only one mode can be default per tokenset

## Next Steps

<CardGroup cols={2}>
  <Card title="Update Mode" icon="pen" href="/api-reference/modes/update">
    Update mode details
  </Card>

  <Card title="Create Tokens" icon="circle" href="/api-reference/tokens/create">
    Add tokens to your mode
  </Card>
</CardGroup>