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

# Create Workspace

> Create a new workspace

# Create Workspace

Creates a new workspace for the authenticated user.

<Note>
  **Write access policy** - This endpoint requires the `write:tokens` scope and API write access on the token owner account.
  Workspace creation is blocked when the owner is at/above their workspace plan limit (existing workspaces stay accessible).
</Note>

## Endpoint

```
POST /workspaces
```

## Authentication

Requires a valid API token in the Authorization header.

## Request

### Headers

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

### Body Parameters

| Parameter     | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `name`        | string | Yes      | Workspace name (max 255 characters) |
| `description` | string | No       | Optional description                |

### Request Body

```json theme={null}
{
  "name": "Design System",
  "description": "Main product design system"
}
```

## Response

### Success Response

**Status:** `201 Created`

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Design System",
  "description": "Main product design system",
  "user_id": "user-123",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}
```

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.tokencraft.dev/api/v1/workspaces \
    -H "Authorization: Bearer tkc_your_token_here" \
    -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 tkc_your_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Design System',
      description: 'Main product design system'
    })
  });

  const workspace = await response.json();
  console.log('Created workspace:', workspace.id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.tokencraft.dev/api/v1/workspaces',
      headers={
          'Authorization': 'Bearer tkc_your_token_here',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Design System',
          'description': 'Main product design system'
      }
  )

  workspace = response.json()
  print(f"Created workspace: {workspace['id']}")
  ```
</CodeGroup>

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": "Name is required and must be a non-empty string"
}
```

**Causes:**

* Missing or empty `name` field
* `name` exceeds 255 characters
* Invalid field types

### 401 Unauthorized

```json theme={null}
{
  "error": "Invalid API token"
}
```

### 403 Forbidden

```json theme={null}
{
  "error": "API write access requires PRO or TEAM plan. Upgrade your plan to create resources via API."
}
```

**Causes:**

* Owner plan does not include API write access
* Owner reached workspace creation limit on current plan

### 500 Internal Server Error

```json theme={null}
{
  "error": "Internal server error"
}
```

## Validation Rules

* **name**: Required, non-empty string, max 255 characters
* **description**: Optional string

## Next Steps

<CardGroup cols={2}>
  <Card title="Update Workspace" icon="pen" href="/api-reference/workspaces/update">
    Update workspace details
  </Card>

  <Card title="Create Tokenset" icon="layer-group" href="/api-reference/tokensets/create">
    Add tokensets to your workspace
  </Card>
</CardGroup>