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

# Update Token

> Update token details

# Update Token

Updates an existing design token. Only provided fields will be updated.

<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

```
PATCH /tokensets/{id}/modes/{modeId}/tokens/{tokenId}
```

## Request

### Path Parameters

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

### Body Parameters

| Parameter     | Type   | Required | Description         |
| ------------- | ------ | -------- | ------------------- |
| `name`        | string | No       | New token name      |
| `type`        | string | No       | New token type      |
| `value`       | string | No       | New token value     |
| `description` | string | No       | New description     |
| `alias_to`    | string | No       | New alias reference |

<Note>
  All body parameters are optional. Only provided fields will be updated.
</Note>

## Response

**Status:** `200 OK`

```json theme={null}
{
  "id": "token-123",
  "tokenset_id": "tokenset-123",
  "mode_id": "mode-light",
  "name": "colors.primary.500",
  "type": "color",
  "value": "#2563eb",
  "description": "Updated primary brand color",
  "alias_to": null,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T14:30:00Z"
}
```

## Examples

<CodeGroup>
  ```bash Update Value theme={null}
  curl -X PATCH https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens/token-123 \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "value": "#2563eb"
    }'
  ```

  ```bash Update Description theme={null}
  curl -X PATCH https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens/token-123 \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "description": "Updated description"
    }'
  ```

  ```bash Convert to Alias theme={null}
  curl -X PATCH https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens/token-123 \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "value": "",
      "alias_to": "colors.blue.500"
    }'
  ```

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

  // Update value
  const response = await fetch(
    `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes/${modeId}/tokens/${tokenId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        value: '#2563eb',
        description: 'Updated primary brand color'
      })
    }
  );

  const token = await response.json();
  ```

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

  response = requests.patch(
      f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens/{token_id}',
      headers={
          'Authorization': 'Bearer tkc_your_token_here',
          'Content-Type': 'application/json'
      },
      json={
          'value': '#2563eb',
          'description': 'Updated primary brand color'
      }
  )

  token = response.json()
  ```
</CodeGroup>

## Error Responses

### 400 Bad Request

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

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

### 404 Not Found

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

## Common Use Cases

### 1. Update Token Value

```javascript theme={null}
await updateToken(tokensetId, modeId, tokenId, {
  value: '#2563eb'
});
```

### 2. Change Token Type

```javascript theme={null}
await updateToken(tokensetId, modeId, tokenId, {
  type: 'dimension',
  value: '16px'
});
```

### 3. Convert to Alias

```javascript theme={null}
await updateToken(tokensetId, modeId, tokenId, {
  value: '',
  alias_to: 'colors.primary.500'
});
```

### 4. Remove Alias

```javascript theme={null}
await updateToken(tokensetId, modeId, tokenId, {
  value: '#3b82f6',
  alias_to: null
});
```

### 5. Batch Updates

```javascript theme={null}
const updates = [
  { tokenId: 'token-1', value: '#3b82f6' },
  { tokenId: 'token-2', value: '#2563eb' },
  { tokenId: 'token-3', value: '#1d4ed8' }
];

for (const { tokenId, value } of updates) {
  await updateToken(tokensetId, modeId, tokenId, { value });
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Delete Token" icon="trash" href="/api-reference/tokens/delete">
    Permanently delete a token
  </Card>

  <Card title="Get Token" icon="circle" href="/api-reference/tokens/get">
    Retrieve token details
  </Card>
</CardGroup>