Create Mode
Creates a new mode (theme variation) within a tokenset.
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
Authentication
Requires a valid API token in the Authorization header.
Request
| 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 dtk_your_token_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Light",
"is_default": true
}'
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
Brand Variations
- Primary Brand
- Secondary Brand
Context Variations
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 };
}
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
