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

# Update Workspace

> Update workspace details

# Update Workspace

Updates an existing workspace. Only provided fields will be updated.

<Note>
  **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.
</Note>

## Endpoint

```
PATCH /workspaces/{id}
```

## 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      | Workspace ID |

### Body Parameters

| Parameter     | Type   | Required | Description                             |
| ------------- | ------ | -------- | --------------------------------------- |
| `name`        | string | No       | New workspace name (max 255 characters) |
| `description` | string | No       | New description (null to remove)        |

<Note>
  All body parameters are optional. Only provided fields will be updated.
</Note>

### Request Body

```json theme={null}
{
  "name": "Updated Design System",
  "description": "Updated description"
}
```

## Response

### Success Response

**Status:** `200 OK`

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

## Examples

<CodeGroup>
  ```bash Update Name theme={null}
  curl -X PATCH https://app.tokencraft.dev/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Design System"
    }'
  ```

  ```bash Update Description theme={null}
  curl -X PATCH https://app.tokencraft.dev/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "description": "New description"
    }'
  ```

  ```bash Remove Description theme={null}
  curl -X PATCH https://app.tokencraft.dev/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer tkc_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "description": null
    }'
  ```

  ```javascript JavaScript theme={null}
  const workspaceId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://app.tokencraft.dev/api/v1/workspaces/${workspaceId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer tkc_your_token_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Updated Design System',
        description: 'Updated description'
      })
    }
  );

  const workspace = await response.json();
  ```

  ```python Python theme={null}
  workspace_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.patch(
      f'https://app.tokencraft.dev/api/v1/workspaces/{workspace_id}',
      headers={
          'Authorization': 'Bearer tkc_your_token_here',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Updated Design System',
          'description': 'Updated description'
      }
  )

  workspace = response.json()
  ```
</CodeGroup>

## Error Responses

### 400 Bad Request

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

**Causes:**

* Empty `name` field
* `name` exceeds 255 characters
* Invalid field types

### 401 Unauthorized

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

### 404 Not Found

```json theme={null}
{
  "error": "Workspace not found"
}
```

**Causes:**

* Workspace ID doesn't exist
* You do not have access to this workspace

## Validation Rules

* **name**: If provided, must be non-empty string, max 255 characters
* **description**: If provided, must be string or null

## Use Cases

### 1. Rename Workspace

```javascript theme={null}
await updateWorkspace(id, { name: 'New Name' });
```

### 2. Update Description

```javascript theme={null}
await updateWorkspace(id, { 
  description: 'Updated project description' 
});
```

### 3. Remove Description

```javascript theme={null}
await updateWorkspace(id, { description: null });
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Delete Workspace" icon="trash" href="/api-reference/workspaces/delete">
    Permanently delete a workspace
  </Card>

  <Card title="Get Workspace" icon="folder" href="/api-reference/workspaces/get">
    Retrieve workspace details
  </Card>
</CardGroup>