Skip to main content

​
Create Workspace

POST /api/client/workspaces

Create a new workspace

​
Authentication

Requires valid JWT token in Authorization header.

​
Request Body

​
name
string
required
Workspace name
​
description
string | null
Workspace description
​
avatar
string | null
Avatar URL or ID

​
Request Schema

export const workspaceCreateInputSchema = z.object({
  name: z.string(),
  description: z.string().nullable().optional(),
  avatar: z.string().nullable().optional(),
});

​
Response

​
id
string
Workspace ID
​
name
string
Workspace name
​
description
string | null
Workspace description
​
avatar
string | null
Avatar URL or ID
​
user
object

​
Error Codes

  • 400 - WorkspaceNameRequired: Workspace name is required
  • 400 - AccountNotFound: Account not found

​
Get Workspace

GET /api/client/workspaces/:workspaceId

Get workspace details

​
Authentication

Requires valid JWT token in Authorization header.

​
Path Parameters

​
workspaceId
string
required
Workspace ID

​
Response

Same schema as Create Workspace response.

​
Error Codes

  • 400 - WorkspaceNotFound: Workspace not found
  • 403 - WorkspaceNoAccess: User does not have access to workspace

​
Update Workspace

PATCH /api/client/workspaces/:workspaceId

Update workspace details

​
Authentication

Requires valid JWT token in Authorization header.

​
Authorization

Only users with owner role can update workspaces.

​
Path Parameters

​
workspaceId
string
required
Workspace ID

​
Request Body

​
name
string
required
Workspace name
​
description
string | null
Workspace description
​
avatar
string | null
Avatar URL or ID

​
Request Schema

export const workspaceUpdateInputSchema = z.object({
  name: z.string(),
  description: z.string().nullable().optional(),
  avatar: z.string().nullable().optional(),
});

​
Response

Returns updated workspace object (same schema as Get Workspace).

​
Behavior

  • Updates workspace metadata
  • Sets updated_at timestamp
  • Sets updated_by to current user ID
  • Publishes workspace.updated event

​
Error Codes

  • 403 - WorkspaceUpdateNotAllowed: Only owners can update workspaces
  • 404 - WorkspaceNotFound: Workspace not found
  • 500 - WorkspaceUpdateFailed: Failed to update workspace

​
Delete Workspace

DELETE /api/client/workspaces/:workspaceId

Delete a workspace

​
Authentication

Requires valid JWT token in Authorization header.

​
Authorization

Only users with owner role can delete workspaces.

​
Path Parameters

​
workspaceId
string
required
Workspace ID

​
Response

Returns deleted workspace object.

​
Behavior

  • Deletes workspace from database
  • Schedules background cleanup job (workspace.clean)
  • Cleanup job has 5 retry attempts with exponential backoff
  • Publishes workspace.deleted event

​
Error Codes

  • 403 - WorkspaceDeleteNotAllowed: Only owners can delete workspaces
  • 404 - WorkspaceNotFound: Workspace not found

​
Invite Users

POST /api/client/workspaces/:workspaceId/users

Invite users to workspace

​
Authentication

Requires valid JWT token in Authorization header.

​
Authorization

Only users with owner or admin role can invite users.

​
Path Parameters

​
workspaceId
string
required
Workspace ID

​
Request Body

​
users
array
required
Array of user objects to invite

​
Request Schema

export const usersCreateInputSchema = z.object({
  users: z.array(z.object({
    email: z.string().email(),
    role: workspaceRoleSchema,
  })),
});

​
Response

​
users
array
Successfully created/existing users
​
errors
array
Failed user invitations

​
Behavior

  • Batch processing: Efficiently handles multiple users
  • Creates missing accounts: Automatically creates pending accounts for new emails
  • Idempotent: Returns existing users if already in workspace
  • Creates self-chat: Each new user gets a private chat node
  • Default limits: Applies configured storage and file size limits
  • Publishes events: Emits user.created event for each new user

​
Error Codes

  • 400 - UserEmailRequired: User email is required
  • 403 - UserInviteNoAccess: Only owners and admins can invite users

​
Update User Role

PATCH /api/client/workspaces/:workspaceId/users/:userId/role

Update user’s role in workspace

​
Authentication

Requires valid JWT token in Authorization header.

​
Authorization

Only users with owner or admin role can update user roles.

​
Path Parameters

​
workspaceId
string
required
Workspace ID
​
userId
string
required
User ID to update

​
Request Body

​
role
WorkspaceRole
required
New role: owner, admin, member, viewer, guest, or none

​
Request Schema

export const userRoleUpdateInputSchema = z.object({
  role: workspaceRoleSchema,
});

​
Response

Returns updated user object (same schema as user in Invite Users response).

​
Role Hierarchy

const ROLE_HIERARCHY = {
  owner: 5,
  admin: 4,
  member: 3,
  viewer: 2,
  guest: 1,
  none: 0,
};

​
Authorization Rules

  • Owners can set any role
  • Admins cannot modify users with equal or higher role
  • Admins cannot grant roles equal to or higher than their own
  • Admins cannot change their own role (except owners)
  • Setting role to none sets status to UserStatus.Removed

​
Behavior

  • Updates user role and status
  • Sets updated_at timestamp
  • Sets updated_by to current account ID
  • Publishes user.updated event

​
Error Codes

  • 403 - UserUpdateNoAccess: Insufficient permissions
  • 404 - UserNotFound: User not found

​
Workspace Roles

Workspace roles determine what actions users can perform.
RoleLevelDescription
owner5Full control over workspace
admin4Manage users and settings
member3Create and edit content
viewer2View-only access
guest1Limited temporary access
none0No access (removed)

​
User Status

export enum UserStatus {
  Active = 1,
  Removed = 2,
}
  • Active: User has access to workspace
  • Removed: User has been removed from workspace

Build docs developers (and LLMs) love

Get started for freeTalk to us