Documentation Menu

Workspace management

Create a new workspace

POST /workspaces/create

Requires authentication.

Create a new workspace. The authenticated user becomes the owner. Workspace names must be unique and a URL-friendly slug is generated automatically.

Request body 

{
  "name": "general"
}

Responses

200 Workspace created

{
  "workspace": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "name": "general",
    "icon_url": "/files/01JQ3KMT6B/download?sig=abc",
    "settings": "string",
    "parsed_settings": {
      "show_join_leave_messages": true,
      "who_can_create_channels": "everyone",
      "who_can_create_invites": "everyone",
      "who_can_pin_messages": "everyone",
      "who_can_manage_custom_emoji": "everyone"
    },
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  }
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Get workspace details

GET /workspaces/{wid}

Requires authentication.

Retrieve details for a workspace including its name, icon, settings, and the current user's membership role.

Parameters

Name In Type Description
wid path string Workspace ID

Responses

200 Workspace details

{
  "workspace": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "name": "general",
    "icon_url": "/files/01JQ3KMT6B/download?sig=abc",
    "settings": "string",
    "parsed_settings": {
      "show_join_leave_messages": true,
      "who_can_create_channels": "everyone",
      "who_can_create_invites": "everyone",
      "who_can_pin_messages": "everyone",
      "who_can_manage_custom_emoji": "everyone"
    },
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Update workspace

POST /workspaces/{wid}/update

Requires authentication.

Update workspace properties such as name or settings. Requires admin or owner role in the workspace.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "name": "general",
  "settings": {
    "show_join_leave_messages": true,
    "who_can_create_channels": "everyone",
    "who_can_create_invites": "everyone",
    "who_can_pin_messages": "everyone",
    "who_can_manage_custom_emoji": "everyone"
  }
}

Responses

200 Workspace updated

{
  "workspace": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "name": "general",
    "icon_url": "/files/01JQ3KMT6B/download?sig=abc",
    "settings": "string",
    "parsed_settings": {
      "show_join_leave_messages": true,
      "who_can_create_channels": "everyone",
      "who_can_create_invites": "everyone",
      "who_can_pin_messages": "everyone",
      "who_can_manage_custom_emoji": "everyone"
    },
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  }
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

List workspace members

POST /workspaces/{wid}/members/list

Requires authentication.

List all members of a workspace with their roles, display names, and ban status.

Parameters

Name In Type Description
wid path string Workspace ID

Responses

200 List of members

{
  "members": [
    {
      "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
      "role": "owner",
      "display_name_override": "string",
      "created_at": "2025-01-15T09:30:00Z",
      "updated_at": "2025-01-15T09:30:00Z",
      "email": "alice@example.com",
      "display_name": "Alice Chen",
      "avatar_url": "/files/01JQ3KMT6B/download?sig=abc",
      "gravatar_url": "https://www.gravatar.com/avatar/abc123?d=mp",
      "is_banned": true
    }
  ]
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Remove a member from workspace

POST /workspaces/{wid}/members/remove

Requires authentication.

Remove a member from the workspace. Admins can remove members, owners can remove anyone except themselves. The removed user loses access to all workspace channels.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V"
}

Responses

200 Member removed

{
  "success": true
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Leave a workspace

POST /workspaces/{wid}/leave

Requires authentication.

Voluntarily leave a workspace. The workspace owner cannot leave without first transferring ownership. Leaving removes access to all channels in the workspace.

Parameters

Name In Type Description
wid path string Workspace ID

Responses

200 Successfully left workspace

{
  "success": true
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Update member role

POST /workspaces/{wid}/members/update-role

Requires authentication.

Change a member's role within the workspace (e.g. member to admin). Only owners can promote to admin, and only admins/owners can change roles. Cannot change your own role.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
  "role": "owner"
}

Responses

200 Role updated

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Create an invite

POST /workspaces/{wid}/invites/create

Requires authentication.

Generate an invite link for the workspace. Invites can be configured with a maximum number of uses and an expiration date. Requires the appropriate permission level configured in workspace settings.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "invited_email": "newuser@example.com",
  "role": "owner",
  "max_uses": 25,
  "expires_in_hours": 0
}

Responses

200 Invite created

{
  "invite": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
    "code": "abc123def",
    "invited_email": "newuser@example.com",
    "role": "owner",
    "created_by": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "max_uses": 25,
    "use_count": 5,
    "expires_at": "2025-01-15T09:30:00Z",
    "created_at": "2025-01-15T09:30:00Z"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

Get notification summaries for all workspaces

GET /workspaces/notifications

Requires authentication.

Get unread message counts and mention counts for all workspaces the current user belongs to. Useful for showing notification badges in the workspace switcher.

Responses

200 Notification summaries per workspace

{
  "workspaces": [
    {
      "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
      "unread_count": 12,
      "notification_count": 3
    }
  ]
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Reorder workspaces for current user

POST /workspaces/reorder

Requires authentication.

Set a custom display order for workspaces in the sidebar. Accepts a mapping of workspace IDs to sort positions. Only affects the current user's view.

Request body 

{
  "workspace_ids": [
    "string"
  ]
}

Responses

200 Workspaces reordered

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Accept an invite

POST /invites/{code}/accept

Requires authentication.

Join a workspace using an invite code. The invite must be valid (not expired, not at max uses). The user is added as a member and automatically joins the workspace's default channels.

Parameters

Name In Type Description
code path string -

Responses

200 Invite accepted

{
  "workspace": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "name": "general",
    "icon_url": "/files/01JQ3KMT6B/download?sig=abc",
    "settings": "string",
    "parsed_settings": {
      "show_join_leave_messages": true,
      "who_can_create_channels": "everyone",
      "who_can_create_invites": "everyone",
      "who_can_pin_messages": "everyone",
      "who_can_manage_custom_emoji": "everyone"
    },
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Upload workspace icon

POST /workspaces/{wid}/icon

Requires authentication.

Upload an image to use as the workspace icon. Accepts JPEG, PNG, GIF, or WebP. The image is resized to fit. Requires admin or owner role.

Parameters

Name In Type Description
wid path string Workspace ID

Request body

Content type: multipart/form-data

Field Type Required Description
file file yes -

Responses

200 Icon uploaded

{
  "icon_url": "/files/01JQ3KMT6B/download?sig=abc"
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

Remove workspace icon

DELETE /workspaces/{wid}/icon

Requires authentication.

Remove the workspace icon, reverting to the default. Requires admin or owner role.

Parameters

Name In Type Description
wid path string Workspace ID

Responses

200 Icon removed

{
  "success": true
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}