> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Create and manage multi-tenant workspaces, members, and invitations.

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.

| 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 settings        |  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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.illumichat.com/api/workspaces" \
    -H "Authorization: Bearer <your-api-key>"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://app.illumichat.com/api/workspaces", {
    headers: { Authorization: "Bearer <your-api-key>" },
  });
  const { data } = await res.json();
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "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.

```bash theme={null}
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"
  }'
```

| Parameter | Type   | Required | Description                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `name`    | string | Yes      | Display name for the workspace.                               |
| `slug`    | string | No       | URL-friendly identifier. Auto-generated from name if omitted. |

**Response** `201 Created`

***

## Get Workspace

Retrieves a workspace by ID.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `204 No Content`

<Warning>
  This action is irreversible. All assistants, conversations, projects, members, and associated data will be permanently deleted.
</Warning>

***

## List Members

Returns all members of a workspace. Uses offset-based pagination.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/members?limit=50" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK`

```json theme={null}
{
  "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.

```bash theme={null}
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" }'
```

| Parameter | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `email`   | string | Yes      | Email address of the user to add.     |
| `role`    | string | Yes      | One 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/invitations" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK`

```json theme={null}
{
  "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.

```bash theme={null}
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" }'
```

<Note>
  Invitations expire after 7 days. The recipient receives an email with a link to accept the invitation.
</Note>

**Response** `201 Created`

***

## Revoke Invitation

Cancels a pending invitation. Requires `owner` or `admin` role.

```bash theme={null}
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/invitations/inv_aaa111" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `204 No Content`

***