> ## 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.

# Workspaces

> Organize your design tokens into workspaces

# Workspaces

Workspaces are the top-level organizational unit in Tokencraft. Each workspace can contain multiple tokensets and serves as a container for related design tokens.

## What is a Workspace?

A workspace is a collection of tokensets that typically represent a single project, product, or design system. Think of it as a folder that groups all your design tokens together.

### Example Structure

```
Workspace: "Mobile App"
├── Tokenset: "Colors"
├── Tokenset: "Typography"
└── Tokenset: "Spacing"

Workspace: "Marketing Website"
├── Tokenset: "Brand Colors"
└── Tokenset: "Components"
```

## Creating a Workspace

You can create workspaces via the UI or API:

<CodeGroup>
  ```bash API theme={null}
  curl -X POST https://app.tokencraft.dev/api/v1/workspaces \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Design System",
      "description": "Main product design system"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.tokencraft.dev/api/v1/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Design System',
      description: 'Main product design system'
    })
  });
  ```
</CodeGroup>

## Workspace Properties

| Property      | Type      | Description          |
| ------------- | --------- | -------------------- |
| `id`          | string    | Unique identifier    |
| `name`        | string    | Workspace name       |
| `description` | string    | Optional description |
| `user_id`     | string    | Owner's user ID      |
| `created_at`  | timestamp | Creation date        |
| `updated_at`  | timestamp | Last update date     |

## Best Practices

### 1. Organize by Project

Create separate workspaces for different projects or products:

* ✅ "Mobile App" workspace
* ✅ "Web Dashboard" workspace
* ✅ "Marketing Site" workspace

### 2. Use Descriptive Names

Make workspace names clear and descriptive:

* ✅ "E-commerce Platform - Design System"
* ❌ "DS1"

### 3. Add Descriptions

Include helpful descriptions:

```json theme={null}
{
  "name": "Mobile App",
  "description": "Design tokens for iOS and Android apps. Includes light and dark modes."
}
```

### 4. One System Per Workspace

Keep related tokens together:

* ✅ All mobile app tokens in one workspace
* ❌ Mixing unrelated projects

## Managing Workspaces

### Listing Workspaces

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.tokencraft.dev/api/v1/workspaces
```

### Getting a Workspace

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.tokencraft.dev/api/v1/workspaces/{workspace_id}
```

### Updating a Workspace

```bash theme={null}
curl -X PATCH https://app.tokencraft.dev/api/v1/workspaces/{workspace_id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "description": "Updated description"
  }'
```

### Deleting a Workspace

```bash theme={null}
curl -X DELETE https://app.tokencraft.dev/api/v1/workspaces/{workspace_id} \
  -H "Authorization: Bearer YOUR_TOKEN"
```

<Warning>
  Deleting a workspace will also delete all its tokensets and tokens. This action cannot be undone.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tokensets" icon="folder" href="/concepts/tokensets">
    Learn about tokensets within workspaces
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/workspaces/list">
    Explore workspace API endpoints
  </Card>
</CardGroup>