Create Token
Creates a new design token in a specific mode.
PRO Plan Required - This endpoint requires a PRO or TEAM subscription plan. API write access is not available on the FREE plan.
Endpoint
POST /api/v1/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 | Yes | Token value |
description | string | No | Optional description |
alias_to | string | No | Reference to another token (for aliases) |
Valid Token Types
color - Color valuesdimension - Sizes and spacingfontFamily - Font familiesfontWeight - Font weightsfontSize - Font sizeslineHeight - Line heightsletterSpacing - Letter spacingduration - Animation durationscubicBezier - Easing functionsnumber - Numeric valuesstrokeStyle - Stroke stylesborder - Border definitionstransition - Transition definitionsshadow - Shadow effectsgradient - Gradient definitionstypography - Complete typography definitions
Response
Status: 201 Created
{
"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
curl -X POST https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/tokens \
-H "Authorization: Bearer dtk_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"name": "colors.primary.500",
"type": "color",
"value": "#3b82f6",
"description": "Primary brand color"
}'
Error Responses
400 Bad Request
{
"error": "Name is required and must be a non-empty string"
}
{
"error": "Type is required and must be one of: color, dimension, ..."
}
{
"error": "Value is required and must be a string"
}
404 Not Found
{
"error": "Mode not found"
}
Naming Convention
Use dot notation for hierarchical organization:
category.subcategory.property.variant
Examples
✅ Good:
colors.primary.500spacing.component.padding.xfont.size.heading.h1
❌ Bad:
primaryColor500spacing_basefontSizeBody
Token Aliases
Create semantic tokens that reference base tokens:
// 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:
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
