Create Token

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

import requests

url = "https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

import requests

url = "https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.tokencraft.dev/api/v1/tokensets/{id}/modes/{modeId}/tokens")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

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	Conditionally	Token value (required unless `alias_to` is provided)
`description`	string	No	Optional description
`alias_to`	string	No	Reference 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"
  }'

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": "spacing.base",
    "type": "dimension",
    "value": "16px",
    "description": "Base spacing unit"
  }'

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": "button.primary.background",
    "type": "color",
    "alias_to": "colors.primary.500"
  }'

const tokensetId = 'tokenset-123';
const modeId = 'mode-light';

// Create color token
const colorToken = await fetch(
  `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes/${modeId}/tokens`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tkc_your_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'colors.primary.500',
      type: 'color',
      value: '#3b82f6',
      description: 'Primary brand color'
    })
  }
).then(r => r.json());

// Create alias token
const aliasToken = await fetch(
  `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes/${modeId}/tokens`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tkc_your_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'button.primary.background',
      type: 'color',
      alias_to: 'colors.primary.500'
    })
  }
).then(r => r.json());

tokenset_id = 'tokenset-123'
mode_id = 'mode-light'

# Create color token
color_token = requests.post(
    f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens',
    headers={
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'colors.primary.500',
        'type': 'color',
        'value': '#3b82f6',
        'description': 'Primary brand color'
    }
).json()

# Create spacing token
spacing_token = requests.post(
    f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens',
    headers={
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'spacing.base',
        'type': 'dimension',
        'value': '16px',
        'description': 'Base spacing unit'
    }
).json()

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

Get Token Update Token

​Create Token

​Endpoint

​Request

​Path Parameters

​Body Parameters

​Valid Token Types

​Response

​Examples

​Error Responses

​400 Bad Request

​404 Not Found

​Naming Convention

​Examples

​Token Aliases

​Batch Creation

​Next Steps

Update Token

List Tokens

Create Token

Endpoint

Request

Path Parameters

Body Parameters

Valid Token Types

Response

Examples

Error Responses

400 Bad Request

404 Not Found

Naming Convention

Examples

Token Aliases

Batch Creation

Next Steps