> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lumenia.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lumenia.net/_mcp/server.

# Workspaces

A **workspace** is a self-contained assistant inside an organization. It has its own LLM settings, its own slice of the organization's knowledge (the documents embedded into it), its own attached tools, and its own channel integrations (voice, WhatsApp, Telegram).

Think of the organization as the shared library, and each workspace as an assistant configured for one purpose (e.g. "Support", "Sales") that draws on part of that library.

## What a workspace is made of

`GET /v1/workspaces/{workspaceId}` returns the settings grouped by concern:

* **chat** — the workspace LLM settings: `mode` (`chat` or `query`), the base `prompt`, `historyLimit`, and `temperature`.
* **knowledgeSearch** — how embedded documents are retrieved: `topResults`, `similarityThreshold`, `queryRefusalMessage`, and (on supported vector databases) `searchMode`.
* **branding** — chat-widget colors and the public `logo` URL.
* **voice / whatsapp / telegram** — the status of each channel integration, inlined. Each reads `{ connected: false }` until set up, and never returns a secret token.
* **counts** — how many documents are embedded and how many tools are attached.

## Chat modes

`chat.mode` controls how strictly the assistant sticks to your embedded documents:

| Mode             | Behavior                                                                                                                                                                                                                          |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chat` (default) | Blends your knowledge base with the model's own general knowledge. When the documents contain nothing relevant, it still answers conversationally from what the model knows.                                                      |
| `query`          | Answers **only** from the embedded documents. If no relevant context is found — or the workspace has no embedded documents at all — it does not fall back to the model; it returns `knowledgeSearch.queryRefusalMessage` instead. |

Use `query` for a strict knowledge-base assistant that must never answer beyond your documents (e.g. support grounded in a specific handbook); use `chat` for a more general, conversational assistant that draws on your documents when helpful but can still talk freely.

> **Info**
>
> A **voice** assistant's knowledge-base lookups **always run in query mode**, regardless of `chat.mode` — they answer strictly from the embedded documents and return `knowledgeSearch.queryRefusalMessage` when nothing relevant is found. (The voice assistant still converses via its own `voice.prompt`; only the document lookup is forced to query mode.)

## The two prompts

A workspace assistant is shaped by **two different prompts**, which is a common point of confusion:

| Prompt         | Where it lives                                                                         | What it governs                                                                                                                                                                                                                                             |
| -------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chat.prompt`  | Workspace settings — `PATCH /v1/workspaces/{workspaceId}`                              | The workspace's **base system prompt**: text chat, and the answers synthesized from the knowledge base — including the knowledge-base replies a voice assistant gives. `chat.temperature` and the whole `knowledgeSearch` group apply to those answers too. |
| `voice.prompt` | The voice integration — `POST`/`PATCH /v1/workspaces/{workspaceId}/integrations/voice` | The **live spoken conversation** on a phone call: the assistant's persona, tone, and flow.                                                                                                                                                                  |

`chat.prompt` exists on every workspace. `voice.prompt` is separate — it belongs to the voice integration.

Both are the workspace's **manual** prompts. Either can be superseded by a partner-owned [prompt template](/documentation/core-concepts/prompt-templates) pinned to the workspace: while a template is assigned to a channel, the rendered template is what actually runs, and the manual prompt for that channel becomes the fallback (it keeps its stored value and stays editable). The `chat` and `voice` groups in the workspace detail report `promptSource` (`manual` or `template`) and a `promptTemplate` object describing the pinned version, so you can always tell which prompt is live.

**Why two?** A live phone call needs different guidance than text — stay concise, sound natural, handle turn-taking — so the spoken conversation gets its own prompt (`voice.prompt`). `chat.prompt` is the workspace's general base system prompt: it shapes the assistant's overall behaviour and persona in chat, *and* it is the prompt used to synthesize knowledge-base answers. Because those knowledge-base answers are generated with `chat.prompt` regardless of how the question arrived, a voice assistant's document answers follow it too. Keeping the two separate lets you tune the spoken persona independently, while the base behaviour and knowledge answers stay consistent across every channel.

> **Info**
>
> **Voice is not active until you create a voice integration.** A new workspace has no voice assistant (`voice` reads `{ connected: false }`) and no `voice.prompt` — only `chat.prompt` applies. Creating the voice integration (see [Voice integration & routing numbers](/documentation/core-concepts/voice-integration)) is what turns the workspace into a phone assistant and gives it a `voice.prompt`.
>
> Once voice is active: to change how the assistant *talks on a call*, edit `voice.prompt`; to change how it *answers from your documents* (on calls or in chat), edit `chat.prompt` and the `knowledgeSearch` settings.

## Knowledge and tools are opt-in

Documents and tools are owned outside the workspace — by the **organization** (or, for tools, possibly by your company as a whole). A workspace uses them by opting in:

* **Documents** — embed an org document into the workspace to make it queryable. See [Documents & knowledge base](/documentation/core-concepts/documents).
* **Tools** — attach an org or partner tool to the workspace to make it callable. A pinned [prompt template](/documentation/core-concepts/prompt-templates#template-tools) can also bring tools along. See [Tools](/documentation/core-concepts/tools).

This means the same document or tool can serve many workspaces, and each workspace exposes only the subset you chose.

## Lifecycle

| Action | Endpoint                                    | Notes                                                                                                      |
| ------ | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| List   | `GET /v1/organizations/{orgId}/workspaces`  | Workspaces are created and listed under their org.                                                         |
| Create | `POST /v1/organizations/{orgId}/workspaces` | Body needs a `name`. A new workspace has no integrations, documents, or tools.                             |
| Read   | `GET /v1/workspaces/{workspaceId}`          | The grouped detail above.                                                                                  |
| Update | `PATCH /v1/workspaces/{workspaceId}`        | Update chat/knowledgeSearch/branding settings.                                                             |
| Delete | `DELETE /v1/workspaces/{workspaceId}`       | Removes the workspace and releases any linked resources (e.g. its voice routing number). Cannot be undone. |

Every workspace call requires the `X-Account-Id` header of the owning account; a workspace id outside that account resolves to `404`.