# Workspaces

Source: https://www.hotdata.dev/docs/api-reference/workspaces
Site index: https://www.hotdata.dev/llms.txt

Workspace management

## List workspaces

`GET /v1/workspaces`

Lists all workspaces in the user's organization.

**Query parameters**

- `organization_public_id` `string` — Filter by organization. Defaults to the user's current organization.

**Response** `200` — Successful response

- `ok` `boolean` — **required**
- `workspaces` `WorkspaceListItem`[] — **required**
  - `public_id` `string` — **required**
  - `name` `string` — **required**
  - `active` `boolean` — **required**
  - `favorite` `boolean` — **required**
  - `provision_status` `string` — **required**

```json
{
  "ok": true,
  "workspaces": [
    {
      "public_id": "workm4lz2mp899l2i7h9lk9u84azg3",
      "name": "production-analytics",
      "active": true,
      "favorite": true,
      "provision_status": "provisioned"
    }
  ]
}
```

**Errors**

| Status | Description |
| ------ | ----------- |
| `401` | Missing or invalid authorization |
| `403` | Forbidden — not a member of the organization or workspace token used |
| `404` | Organization not found |

## Create a workspace

`POST /v1/workspaces`

Creates a new workspace in the specified organization.

**Request body**

- `name` `string` — **required**. Name for the new workspace.
- `organization_public_id` `string` — Target organization. Defaults to the user's current organization.

```json
{
  "name": "production-analytics"
}
```

**Response** `201` — Workspace created

- `ok` `boolean` — **required**
- `workspace` `WorkspaceDetail` — **required**
  - `public_id` `string` — **required**
  - `name` `string` — **required**
  - `provision_status` `string` — **required**

```json
{
  "ok": true,
  "workspace": {
    "public_id": "workm4lz2mp899l2i7h9lk9u84azg3",
    "name": "production-analytics",
    "provision_status": "pending"
  }
}
```

**Errors**

| Status | Description |
| ------ | ----------- |
| `400` | Invalid JSON body |
| `401` | Missing or invalid authorization |
| `403` | Forbidden |
| `404` | Organization not found |
| `422` | Validation error (e.g. name required) |

## Delete a workspace

`DELETE /v1/workspaces/{public_id}`

Hard-deletes the workspace. Namespace, storage, and catalog deprovisioning runs asynchronously after the row is removed.

**Response** `204` — Workspace deleted

**Errors**

| Status | Description |
| ------ | ----------- |
| `401` | Missing or invalid authorization |
| `403` | Workspace-scoped tokens are not allowed |
| `404` | Workspace not found, or caller is not a member of its organization |