Workspaces
API endpoints for Workspaces
/api/workspaces List lists all workspaces for the current user.
Returns a paginated list of workspaces the authenticated user belongs to. Supports optional page and per_page query parameters for pagination. Returns 401 if not authenticated.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 500 | Internal server error |
Success
Response response.PaginatedWorkspaces
Paginated Workspaces
| Property | Type | Description |
|---|---|---|
| data | string[] | Array of workspaces for current page |
| meta | string | Pagination metadata |
/api/workspaces Create creates a new workspace.
Creates a new workspace with the authenticated user as owner and default 88Agents integrations. Validates the request payload. IMPORTANT: Users can only own ONE workspace. If the user already owns a workspace, this endpoint returns 403 Forbidden. Users can be members of multiple workspaces, but ownership is limited to one workspace per user. Returns 400 if validation fails, 403 if user already owns a workspace, 201 with the new workspace on success.
Request Body request.Workspace
Workspace
| Property | Type | Description |
|---|---|---|
| title* | string | Workspace name |
| description | string | null | Optional description of workspace purpose |
Response Codes
| Status Code | Description |
|---|---|
| 201 | Resource created successfully |
| 400 | Invalid request |
| 403 | Permission denied |
| 500 | Internal server error |
Resource created successfully
Response response.WorkspaceResponse
Workspace
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique workspace identifier |
| name | string | Workspace name (deprecated, use Title) |
| title | string | Workspace name |
| description | string | null | Optional description of workspace purpose |
| logo | string | null | Workspace logo filename |
| logo_url | string | null | Full URL to workspace logo |
| max_doc_size | integer (int64) | Maximum document size in bytes |
| max_agent_size | integer (int64) | Maximum total agent knowledge size in bytes |
| settings | object | Workspace settings as JSON object |
| onboarding | object | Onboarding state as JSON object |
| onboarding_completed_at | string (date-time) | null | Timestamp when onboarding was completed |
| trial_ends_at | string (date-time) | null | Timestamp when trial period ends |
| role | string | Current user's role in workspace (owner, admin, member) |
| agent_limits | string | null | Agent creation limits for this workspace |
| created_at | string (date-time) | Timestamp when workspace was created |
| updated_at | string (date-time) | Timestamp when workspace was last updated |
/api/workspaces/{workspace_id} Get retrieves a workspace.
Returns a single workspace by ID with the current user's role and agent limits based on the workspace's subscription plan. The workspace is loaded from middleware context. Returns 404 if workspace not found or user is not a member.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
/api/workspaces/{workspace_id} Update updates a workspace.
Updates an existing workspace's title, description, or settings. Only fields provided in the request are updated. Returns 400 if validation fails, 404 if workspace not found.
Request Body request.WorkspaceUpdate
Workspace Update
| Property | Type | Description |
|---|---|---|
| title | string | null | Workspace name |
| description | string | null | Optional description of workspace purpose |
| settings | object | Workspace settings as JSON object |
| onboarding | object | Onboarding state as JSON object |
| onboarding_completed_at | string | null | ISO timestamp when onboarding was completed |
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 500 | Internal server error |
Success
Response response.WorkspaceResponse
Workspace
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique workspace identifier |
| name | string | Workspace name (deprecated, use Title) |
| title | string | Workspace name |
| description | string | null | Optional description of workspace purpose |
| logo | string | null | Workspace logo filename |
| logo_url | string | null | Full URL to workspace logo |
| max_doc_size | integer (int64) | Maximum document size in bytes |
| max_agent_size | integer (int64) | Maximum total agent knowledge size in bytes |
| settings | object | Workspace settings as JSON object |
| onboarding | object | Onboarding state as JSON object |
| onboarding_completed_at | string (date-time) | null | Timestamp when onboarding was completed |
| trial_ends_at | string (date-time) | null | Timestamp when trial period ends |
| role | string | Current user's role in workspace (owner, admin, member) |
| agent_limits | string | null | Agent creation limits for this workspace |
| created_at | string (date-time) | Timestamp when workspace was created |
| updated_at | string (date-time) | Timestamp when workspace was last updated |
/api/workspaces/{workspace_id} Delete deletes a workspace.
Soft-deletes a workspace by ID. Only the workspace owner can delete it. Cannot delete the user's last workspace. Returns 400 if it's the last workspace, 403 if not owner, 404 if not found.
Response Codes
| Status Code | Description |
|---|---|
| 204 | Success with no content |
| 400 | Invalid request |
| 403 | Permission denied |
| 500 | Internal server error |