Workspaces | LumenOne's API Docs

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.

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

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) 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.
Tools — attach an org or partner tool to the workspace to make it callable. A pinned prompt template can also bring tools along. See 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.