Workspaces

Workspaces are the top-level organizational unit. Each workspace contains documents and members with specific roles.

Base Path: /api/v1/workspaces Authentication: Required (Bearer Token) Tag: Workspaces

---

List Workspaces

Retrieve all workspaces the authenticated user belongs to.

GET /workspaces

Response

{
  "success": true,
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Engineering Team",
      "description": "Technical documentation workspace",
      "icon": "🏗️",
      "color": "#4A90D9",
      "ownerId": "880e8400-e29b-41d4-a716-446655440000",
      "isDefault": true,
      "isArchived": false,
      "documentCount": 42,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ]
}

Response Type: ApiResponse<List<WorkspaceResponse>>

---

Get Workspace

Retrieve a single workspace by ID.

GET /workspaces/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Workspace ID

Response Type: ApiResponse<WorkspaceResponse>

---

Create Workspace

Create a new workspace. The authenticated user becomes the owner.

POST /workspaces

Request Body

{
  "name": "New Workspace",
  "description": "A workspace for the team",
  "icon": "🚀",
  "color": "#FF5733"
}

Field	Type	Required	Validation	Description
name	String	Yes	Not blank, max 255 chars	Workspace name
description	String	No	Max 1000 chars	Description
icon	String	No	Max 50 chars	Workspace icon/emoji
color	String	No	Max 20 chars	Theme color (hex)

Response

Status: 201 Created Response Type: ApiResponse<WorkspaceResponse>

---

Update Workspace

Update workspace properties.

PUT /workspaces/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Workspace ID

Request Body

{
  "name": "Updated Name",
  "description": "Updated description",
  "icon": "📋",
  "color": "#28A745",
  "isArchived": false
}

Field	Type	Required	Validation	Description
name	String	No	Max 255 chars	New name
description	String	No	Max 1000 chars	New description
icon	String	No	Max 50 chars	New icon
color	String	No	Max 20 chars	New color
isArchived	Boolean	No	-	Archive status

Response Type: ApiResponse<WorkspaceResponse>

:::info Required Role ADMIN or OWNER role required to update a workspace. :::

---

Delete Workspace

Delete a workspace and all associated data.

DELETE /workspaces/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Workspace ID

Response Type: ApiResponse<Void>

danger

Only the workspace OWNER can delete a workspace. This action is irreversible.