Skip to main content
Workspaces are the top-level organizational unit in IllumiChat. Every assistant, conversation, project, and member belongs to a workspace. Use these endpoints to manage workspace settings, membership, and invitations.

​
Role Permissions

Each workspace member has one of four roles. The table below summarizes what each role can do.
ActionOwnerAdminMemberGuest
View workspaceYesYesYesYes
Use assistantsYesYesYesRead-only
Create assistantsYesYesNoNo
Manage assistantsYesYesNoNo
Manage membersYesYesNoNo
Manage invitationsYesYesNoNo
Update workspace settingsYesYesNoNo
Configure settingsYesYesNoNo
Manage billingYesNoNoNo
Delete workspaceYesNoNoNo
Transfer ownershipYesNoNoNo

​
List Workspaces

Returns all workspaces the authenticated user belongs to. 
curl -X GET "https://app.illumichat.com/api/workspaces" \
  -H "Authorization: Bearer <your-api-key>"
Response 200 OK 
{
  "data": [
    {
      "id": "ws_abc123",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "plan": "pro",
      "role": "owner",
      "createdAt": "2025-06-15T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}

​
Create Workspace

Creates a new workspace. The authenticated user becomes the owner. 
curl -X POST "https://app.illumichat.com/api/workspaces" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp"
  }'
ParameterTypeRequiredDescription
namestringYesDisplay name for the workspace.
slugstringNoURL-friendly identifier. Auto-generated from name if omitted.
Response 201 Created

​
Get Workspace

Retrieves a workspace by ID. 
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123" \
  -H "Authorization: Bearer <your-api-key>"
Response 200 OK with the full workspace object including memberCount, assistantCount, and timestamps.

​
Update Workspace

Updates workspace settings. Requires owner or admin role. 
curl -X PATCH "https://app.illumichat.com/api/workspaces/ws_abc123" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corporation" }'
Response 200 OK with the updated workspace object.

​
Delete Workspace

Permanently deletes a workspace and all associated data. Requires owner role. 
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123" \
  -H "Authorization: Bearer <your-api-key>"
Response 204 No Content
This action is irreversible. All assistants, conversations, projects, members, and associated data will be permanently deleted.

​
List Members

Returns all members of a workspace. Uses offset-based pagination. 
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/members?limit=50" \
  -H "Authorization: Bearer <your-api-key>"
Response 200 OK 
{
  "data": [
    {
      "id": "mem_aaa111",
      "userId": "user_xyz",
      "email": "alice@acme.com",
      "name": "Alice Chen",
      "role": "owner",
      "joinedAt": "2025-06-15T10:30:00Z"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

​
Add Member

Adds an existing IllumiChat user to the workspace. Requires owner or admin role. 
curl -X POST "https://app.illumichat.com/api/workspaces/ws_abc123/members" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "email": "bob@acme.com", "role": "member" }'
ParameterTypeRequiredDescription
emailstringYesEmail address of the user to add.
rolestringYesOne of admin, member, or guest.
Response 201 Created

​
Update Member Role

Changes a member’s role. Requires owner or admin role. Owners cannot be demoted by admins. 
curl -X PATCH "https://app.illumichat.com/api/workspaces/ws_abc123/members/mem_aaa111" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'
Response 200 OK with the updated member object.

​
Remove Member

Removes a member from the workspace. Requires owner or admin role. The workspace owner cannot be removed. 
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/members/mem_aaa111" \
  -H "Authorization: Bearer <your-api-key>"
Response 204 No Content

​
List Invitations

Returns all pending invitations for the workspace. 
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/invitations" \
  -H "Authorization: Bearer <your-api-key>"
Response 200 OK 
{
  "data": [
    {
      "id": "inv_aaa111",
      "email": "carol@acme.com",
      "role": "member",
      "status": "pending",
      "invitedBy": "user_xyz",
      "expiresAt": "2025-10-01T00:00:00Z",
      "createdAt": "2025-09-24T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}

​
Create Invitation

Sends an email invitation to join the workspace. Requires owner or admin role. 
curl -X POST "https://app.illumichat.com/api/workspaces/ws_abc123/invitations" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "email": "carol@acme.com", "role": "member" }'
Invitations expire after 7 days. The recipient receives an email with a link to accept the invitation.
Response 201 Created

​
Revoke Invitation

Cancels a pending invitation. Requires owner or admin role. 
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/invitations/inv_aaa111" \
  -H "Authorization: Bearer <your-api-key>"
Response 204 No Content