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, invitations, and AI model configuration.
Role Permissions
Each workspace member has one of four roles. The table below summarizes what each role can do.
| Action | Owner | Admin | Member | Guest |
|---|
| View workspace | Yes | Yes | Yes | Yes |
| Use assistants | Yes | Yes | Yes | Read-only |
| Create assistants | Yes | Yes | No | No |
| Manage assistants | Yes | Yes | No | No |
| Manage members | Yes | Yes | No | No |
| Manage invitations | Yes | Yes | No | No |
| Update workspace settings | Yes | Yes | No | No |
| Configure models | Yes | Yes | No | No |
| Manage billing | Yes | No | No | No |
| Delete workspace | Yes | No | No | No |
| Transfer ownership | Yes | No | No | No |
List Workspaces
Returns all workspaces the authenticated user belongs to.
curl -X GET "https://beta.illumichat.com/api/workspaces" \
-H "Authorization: Bearer <your-api-key>"
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://beta.illumichat.com/api/workspaces" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Corp",
"slug": "acme-corp"
}'
| Parameter | Type | Required | Description |
|---|
name | string | Yes | Display name for the workspace. |
slug | string | No | URL-friendly identifier. Auto-generated from name if omitted. |
201 Created
Get Workspace
Retrieves a workspace by ID.
curl -X GET "https://beta.illumichat.com/api/workspaces/ws_abc123" \
-H "Authorization: Bearer <your-api-key>"
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://beta.illumichat.com/api/workspaces/ws_abc123" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme Corporation" }'
200 OK with the updated workspace object.
Delete Workspace
Permanently deletes a workspace and all associated data. Requires owner role.
curl -X DELETE "https://beta.illumichat.com/api/workspaces/ws_abc123" \
-H "Authorization: Bearer <your-api-key>"
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://beta.illumichat.com/api/workspaces/ws_abc123/members?limit=50" \
-H "Authorization: Bearer <your-api-key>"
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://beta.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" }'
| Parameter | Type | Required | Description |
|---|
email | string | Yes | Email address of the user to add. |
role | string | Yes | One of admin, member, or guest. |
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://beta.illumichat.com/api/workspaces/ws_abc123/members/mem_aaa111" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{ "role": "admin" }'
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://beta.illumichat.com/api/workspaces/ws_abc123/members/mem_aaa111" \
-H "Authorization: Bearer <your-api-key>"
204 No Content
List Invitations
Returns all pending invitations for the workspace.
curl -X GET "https://beta.illumichat.com/api/workspaces/ws_abc123/invitations" \
-H "Authorization: Bearer <your-api-key>"
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://beta.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.
201 Created
Revoke Invitation
Cancels a pending invitation. Requires owner or admin role.
curl -X DELETE "https://beta.illumichat.com/api/workspaces/ws_abc123/invitations/inv_aaa111" \
-H "Authorization: Bearer <your-api-key>"
204 No Content
Get Workspace Models
Retrieves the AI model configuration for a workspace.
curl -X GET "https://beta.illumichat.com/api/workspaces/ws_abc123/models" \
-H "Authorization: Bearer <your-api-key>"
200 OK
{
"data": {
"defaultModel": "grok-2",
"allowedModels": ["grok-2", "grok-3", "gpt-4o", "gpt-4o-mini"],
"updatedAt": "2025-09-01T14:00:00Z"
}
}
Update Workspace Models
Configures which AI models are available in the workspace and sets the default. Requires owner or admin role.
curl -X PATCH "https://beta.illumichat.com/api/workspaces/ws_abc123/models" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"defaultModel": "grok-3",
"allowedModels": ["grok-2", "grok-3", "gpt-4o"]
}'
| Parameter | Type | Required | Description |
|---|
defaultModel | string | No | Model used by new assistants when no model is specified. |
allowedModels | string[] | No | Models that assistants in this workspace may use. |
The defaultModel must be included in the allowedModels array. If you update allowedModels without including the current default, the API returns a 422 validation error.
200 OK with the updated model configuration. 
