Skip to main content
POST
/
tokensets
/
{id}
/
modes
/
{modeId}
/
tokens
Create Token
curl --request POST \
  --url https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens \
  --header 'Authorization: Bearer <token>'

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

Creates a new design token in a specific mode.
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.

​
Endpoint

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

​
Request

​
Path Parameters

ParameterTypeRequiredDescription
idstringYesTokenset ID
modeIdstringYesMode ID

​
Body Parameters

ParameterTypeRequiredDescription
namestringYesToken name (dot notation, e.g., colors.primary.500)
typestringYesToken type (see valid types below)
valuestringConditionallyToken value (required unless alias_to is provided)
descriptionstringNoOptional description
alias_tostringNoReference 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 
{
  "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 tkc_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 (unless alias_to is provided)"
}

​
404 Not Found

{
  "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: 
// 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

Update Token

Update token details

List Tokens

View all tokens