Update Token
Updates an existing design token. Only provided fields will be updated.
PRO Plan Required - This endpoint requires a PRO or TEAM subscription plan. API write access is not available on the FREE plan.
Endpoint
PATCH /api/v1/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 |
All body parameters are optional. Only provided fields will be updated.
Response
Status: 200 OK
{
"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
curl -X PATCH https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens/token-123 \
-H "Authorization: Bearer dtk_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"value": "#2563eb"
}'
Error Responses
400 Bad Request
{
"error": "Name must be a non-empty string"
}
{
"error": "Type must be one of: color, dimension, ..."
}
404 Not Found
{
"error": "Token not found"
}
Common Use Cases
1. Update Token Value
await updateToken(tokensetId, modeId, tokenId, {
value: '#2563eb'
});
2. Change Token Type
await updateToken(tokensetId, modeId, tokenId, {
type: 'dimension',
value: '16px'
});
3. Convert to Alias
await updateToken(tokensetId, modeId, tokenId, {
value: '',
alias_to: 'colors.primary.500'
});
4. Remove Alias
await updateToken(tokensetId, modeId, tokenId, {
value: '#3b82f6',
alias_to: null
});
5. Batch Updates
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
