---
audience: developer
summary: Workspaces, members, settings, and the workspace-bridge surface.
title: Workspaces API
path: reference/api/workspaces
status: published
---

# Workspaces API

19 endpoints, all under `/v1/workspaces/`.

## Workspace CRUD

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/workspaces` | List workspaces you're a member of. |
| `POST` | `/v1/workspaces` | Create a new workspace. |
| `GET` | `/v1/workspaces/{id}` | One workspace with metadata + members count. |
| `PATCH` | `/v1/workspaces/{id}` | Update name, description, settings. |
| `DELETE` | `/v1/workspaces/{id}` | Delete (owner only; archives if not empty). |

### POST /v1/workspaces

```jsonc
{
  "name": "Project Lighthouse",
  "slug": "lighthouse",          // optional; defaults to slugified name
  "description": "Q3 launch coordination",
  "icon": "🏗️"
}
```

## Workspace members

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/workspaces/{id}/members` | List with roles. |
| `POST` | `/v1/workspaces/{id}/members` | Add a member (with `role`). |
| `PATCH` | `/v1/workspaces/{id}/members/{participant_id}` | Change role. |
| `DELETE` | `/v1/workspaces/{id}/members/{participant_id}` | Remove. |

Roles: `owner`, `editor`, `viewer`.

## Settings

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/workspaces/{id}/settings` | Read settings. |
| `PUT` | `/v1/workspaces/{id}/settings` | Update settings. |
| `PUT` | `/v1/workspaces/{id}/today-pin` | Pin a note as the workspace's "Today". |

Settings keys (all optional):

- `todo_block_ids_enabled` (default `true`) — controls whether the parser writes `^todo-<id>` block ids.
- `default_response_mode` (`streaming` / `conversational`).
- `default_engagement_mode` (`always` / `mention` / `keyword` / `autonomous`).
- `today_pinned_note_id` — same as `PUT /today-pin`.
- `theme` — UI theme override.

## Workspace bridges

A workspace bridge connects a workspace to an external system (e.g.
a Notion database, a SharePoint folder). The AI can read/write the
external side via the `scaiwave.workspace_bridge` plugin.

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/workspaces/{id}/bridges` | List bridges. |
| `POST` | `/v1/workspaces/{id}/bridges` | Create a bridge. |
| `PATCH` | `/v1/workspaces/{id}/bridges/{bridge_id}` | Update. |
| `DELETE` | `/v1/workspaces/{id}/bridges/{bridge_id}` | Remove. |

(Different from [room bridges](/docs/scaiwave/reference/api/bridges) —
those mirror chat, these expose external data sources to the AI.)

## Errors

- `SW_WORKSPACE_NOT_FOUND`
- `SW_WORKSPACE_FORBIDDEN` — caller isn't a member.
- `SW_WORKSPACE_NEEDS_OWNER` — operation requires `owner` role.
- `SW_WORKSPACE_SLUG_TAKEN`