API Introduction

Getting started with the Tokencraft REST API

Tokencraft REST API

The Tokencraft API is a RESTful API that provides programmatic access to your design tokens. Use it to integrate Tokencraft into your build process, CI/CD pipeline, or any application.

Base URL

https://app.tokencraft.dev/api/v1

For local development:

http://localhost:3000/api/v1

Authentication

All API requests require authentication using Bearer tokens in the Authorization header:

Authorization: Bearer dtk_your_token_here

See Authentication for details on creating and managing API tokens.

Request Format

The API accepts and returns JSON. Always include the Content-Type header for POST/PATCH requests:

curl -X POST https://app.tokencraft.dev/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Workspace"}'

Response Format

Success Response

{
  "workspaces": [...],
  "total": 10
}

Error Response

{
  "error": "Error message"
}

Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing token
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limiting

• Limit: 100 requests per minute per API token
• Headers: Rate limit information is included in response headers

See Rate Limits for details.

Endpoints Overview

Workspaces

• GET /workspaces - List all workspaces
• POST /workspaces - Create a workspace
• GET /workspaces/{id} - Get a workspace
• PATCH /workspaces/{id} - Update a workspace
• DELETE /workspaces/{id} - Delete a workspace
• GET /workspaces/{id}/tokensets - List tokensets in a workspace

Tokensets

• GET /tokensets/{id} - Get a tokenset
• PATCH /tokensets/{id} - Update a tokenset
• DELETE /tokensets/{id} - Delete a tokenset
• GET /tokensets/{id}/modes - List modes
• POST /tokensets/{id}/modes - Create a mode
• GET /tokensets/{id}/tokens - Get all tokens

Tokens

• GET /tokensets/{id}/modes/{modeId}/tokens - List tokens in a mode
• POST /tokensets/{id}/modes/{modeId}/tokens - Create a token
• GET /tokensets/{id}/modes/{modeId}/tokens/{name} - Get a token
• PATCH /tokensets/{id}/modes/{modeId}/tokens/{name} - Update a token
• DELETE /tokensets/{id}/modes/{modeId}/tokens/{name} - Delete a token

Export

• GET /tokensets/{id}/export - Export all modes
• GET /tokensets/{id}/modes/{modeId}/export - Export a specific mode

Quick Start

1. Get Your Workspaces

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.tokencraft.dev/api/v1/workspaces

2. Get Tokensets

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.tokencraft.dev/api/v1/workspaces/{workspace_id}/tokensets

3. Export Tokens

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/export?format=css"

SDKs and Libraries

JavaScript/TypeScript

class TokencraftAPI {
  constructor(token) {
    this.token = token;
    this.baseUrl = 'https://app.tokencraft.dev/api/v1';
  }

  async getWorkspaces() {
    const response = await fetch(`${this.baseUrl}/workspaces`, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return response.json();
  }

  async exportTokens(tokensetId, modeId, format = 'json') {
    const response = await fetch(
      `${this.baseUrl}/tokensets/${tokensetId}/modes/${modeId}/export?format=${format}`,
      { headers: { 'Authorization': `Bearer ${this.token}` } }
    );
    return response.text();
  }
}

// Usage
const api = new TokencraftAPI('dtk_your_token_here');
const workspaces = await api.getWorkspaces();

Python

import requests

class TokencraftAPI:
    def __init__(self, token):
        self.token = token
        self.base_url = 'https://app.tokencraft.dev/api/v1'
        self.headers = {'Authorization': f'Bearer {token}'}
    
    def get_workspaces(self):
        response = requests.get(
            f'{self.base_url}/workspaces',
            headers=self.headers
        )
        return response.json()
    
    def export_tokens(self, tokenset_id, mode_id, format='json'):
        response = requests.get(
            f'{self.base_url}/tokensets/{tokenset_id}/modes/{mode_id}/export',
            params={'format': format},
            headers=self.headers
        )
        return response.text

# Usage
api = TokencraftAPI('dtk_your_token_here')
workspaces = api.get_workspaces()

Best Practices

1. Use Environment Variables

Never hard-code tokens:

export TOKENCRAFT_TOKEN="dtk_your_token_here"
export TOKENCRAFT_API_BASE="https://app.tokencraft.dev/api/v1"

2. Handle Errors

Always check response status:

const response = await fetch(url, { headers });

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error || 'API request failed');
}

const data = await response.json();

3. Respect Rate Limits

Implement exponential backoff for 429 responses:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status !== 429) {
      return response;
    }
    
    // Wait before retrying (exponential backoff)
    await new Promise(resolve => 
      setTimeout(resolve, Math.pow(2, i) * 1000)
    );
  }
  
  throw new Error('Max retries exceeded');
}

4. Cache Responses

Design tokens don’t change frequently:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedTokens(tokensetId, modeId) {
  const cacheKey = `${tokensetId}-${modeId}`;
  const cached = cache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await fetchTokens(tokensetId, modeId);
  cache.set(cacheKey, { data, timestamp: Date.now() });
  
  return data;
}

Next Steps

Authentication

Learn about API authentication

Workspaces

Manage workspaces

Export

Export tokens in multiple formats

Errors

Handle errors properly