Create Mode

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

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

fetch('https://app.tokencraft.dev/api/v1/tokensets/{id}/modes', 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",
  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"

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

}

require 'uri'
require 'net/http'

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

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

Create Mode

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

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

fetch('https://app.tokencraft.dev/api/v1/tokensets/{id}/modes', 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",
  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"

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

}

require 'uri'
require 'net/http'

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

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 Mode

Creates a new mode (theme variation) within a tokenset.

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

Authentication

Requires a valid API token in the Authorization header.

Request

Headers

Header	Value	Required
`Authorization`	Bearer token	Yes
`Content-Type`	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Tokenset ID

Body Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Mode name (max 255 characters)
`is_default`	boolean	No	Whether this mode is the default (default: false)

If is_default is true, all other modes in this tokenset will be set to non-default.

Request Body

{
  "name": "Dark",
  "is_default": false
}

Response

Success Response

Status: 201 Created

{
  "id": "mode-dark",
  "tokenset_id": "tokenset-123",
  "name": "Dark",
  "is_default": false,
  "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 \
  -H "Authorization: Bearer tkc_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Light",
    "is_default": true
  }'

curl -X POST https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes \
  -H "Authorization: Bearer tkc_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dark"
  }'

const tokensetId = 'tokenset-123';

// Create light mode as default
const lightMode = await fetch(
  `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tkc_your_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Light',
      is_default: true
    })
  }
).then(r => r.json());

// Create dark mode
const darkMode = await fetch(
  `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tkc_your_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Dark',
      is_default: false
    })
  }
).then(r => r.json());

tokenset_id = 'tokenset-123'

# Create light mode as default
light_mode = requests.post(
    f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes',
    headers={
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
    },
    json={'name': 'Light', 'is_default': True}
).json()

# Create dark mode
dark_mode = requests.post(
    f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes',
    headers={
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
    },
    json={'name': 'Dark', 'is_default': False}
).json()

Error Responses

400 Bad Request

{
  "error": "Name is required and must be a non-empty string"
}

{
  "error": "is_default must be a boolean"
}

404 Not Found

{
  "error": "Tokenset not found"
}

Common Mode Names

Theme Variations

Light
Dark
High Contrast

Platform Variations

Web
Mobile
Desktop

Brand Variations

Primary Brand
Secondary Brand

Context Variations

Marketing
Product
Admin

Use Cases

1. Create Light/Dark Themes

async function setupThemes(tokensetId) {
  const light = await createMode(tokensetId, {
    name: 'Light',
    is_default: true
  });
  
  const dark = await createMode(tokensetId, {
    name: 'Dark'
  });
  
  return { light, dark };
}

2. Create Multi-Platform Modes

const platforms = ['Web', 'iOS', 'Android'];

for (const platform of platforms) {
  await createMode(tokensetId, {
    name: platform,
    is_default: platform === 'Web'
  });
}

Default Mode Behavior

When setting a mode as default:

The new mode’s is_default is set to true
All other modes in the tokenset are set to is_default: false
Only one mode can be default per tokenset

Next Steps

Update Mode

Update mode details

Create Tokens

Add tokens to your mode

Overview

Workspaces

Tokensets

Modes

Tokens

Export

Create Mode

Create Mode

Endpoint

Authentication

Request

Headers

Path Parameters

Body Parameters

Request Body

Response

Success Response

Examples

Error Responses

400 Bad Request

404 Not Found

Common Mode Names

Theme Variations

Platform Variations

Brand Variations

Context Variations

Use Cases

1. Create Light/Dark Themes

2. Create Multi-Platform Modes

Default Mode Behavior

Next Steps

Update Mode

Create Tokens

​Create Mode

​Endpoint

​Authentication

​Request

​Headers

​Path Parameters

​Body Parameters

​Request Body

​Response

​Success Response

​Examples

​Error Responses

​400 Bad Request

​404 Not Found

​Common Mode Names

​Theme Variations

​Platform Variations

​Brand Variations

​Context Variations

​Use Cases

​1. Create Light/Dark Themes

​2. Create Multi-Platform Modes

​Default Mode Behavior

​Next Steps

Update Mode

Create Tokens

Create Mode

Endpoint

Authentication

Request

Headers

Path Parameters

Body Parameters

Request Body

Response

Success Response

Examples

Error Responses

400 Bad Request

404 Not Found

Common Mode Names

Theme Variations

Platform Variations

Brand Variations

Context Variations

Use Cases

1. Create Light/Dark Themes

2. Create Multi-Platform Modes

Default Mode Behavior

Next Steps