Managing namespaces

A namespace is a separate index inside your account. Sources, search and the ledger each work inside one, and an agent names the one it wants with every request. Everyone with access to a namespace can see everything indexed in it, so use separate namespaces to keep material apart. For the idea behind them, see Namespaces.

In the API and in some error messages, a namespace is called a "workspace".

The namespace switcher

The switcher sits at the top of the console's sidebar, under the label Namespace. It shows the name of the namespace you are working in.

Open it to see every namespace you can reach, each with its name and its id. Choose one to switch to it. The menu also has New namespace… (Owners and Admins) and Manage namespaces, which opens the Namespaces page. Your browser remembers the last namespace you chose.

What follows the switcher:

• Overview, Search, Ledger, Sources and Repositories show only the selected namespace. So does the count of failing sources next to Sources in the sidebar.
• A source you add goes into the selected namespace.
• Connect your agent, on the API keys page, shows the configuration for the selected namespace.

The Team and Namespaces pages, and the list of your keys on API keys, don't change with the switcher.

Create a namespace

You need the Owner or Admin role.

1. Open the namespace switcher and select New namespace…. Or open Namespaces, and use the name field at the top of the list.
2. Enter a name, for example "Research". Names can be up to 80 characters.
3. Select Create namespace, or Create on the Namespaces page.

Workstate creates an id for it, such as ws-3f2a…: ws- followed by 32 hexadecimal characters. You name the namespace; you can't choose its id. The console switches to the new namespace straight away. Next, add a source to it on the Sources page. See Sources.

Who gets access to a new namespace

When a namespace is created, Workstate gives access to the person who created it and to every Owner and Admin on the account at that moment. Nobody else gets it automatically: not Members, and not anyone who joins the account later.

To give someone else access, tick the namespace when you invite them, or later in the Namespaces column on the Team page. You can give only namespaces you hold. See Change who reaches a namespace.

The Namespaces page

The Namespaces page lists every namespace you can reach:

Column	What it shows
Name	The namespace's name. Current marks the one you are working in
Namespace id	The id an agent sends. The copy button next to it copies the id
Your role	Your role in that namespace
Sources	How many sources it indexes
Created	When it was created

Use Switch to on a row to work in that namespace.

Choose a namespace for each request

An agent names the namespace it wants in the X-RAG-Namespace header, using the namespace's id:

• The id must be one your API key has access to. Otherwise the request is refused with "no grant for namespace …".
• If an agent sends no header, it gets your oldest namespace.

Copy an id from the Namespace id column, or read it in the switcher.

Connect an agent to several namespaces

The Connect your agent panel on the API keys page shows the configuration for the selected namespace only. Each namespace's pair of servers has its own names:

• Your oldest namespace gets rag-corpus and rag-ledger.
• Each other namespace gets rag-corpus-<namespace id> and rag-ledger-<namespace id>.

To connect one agent to several namespaces:

1. Open API keys.
2. Select a namespace in the switcher, then select Copy in Connect your agent.
3. Repeat for each namespace, and put every server in one mcpServers list. The names differ, so no server overwrites another.

For two namespaces, the combined file looks like this:

Illustrative

These namespace ids are examples.

{
  "mcpServers": {
    "rag-corpus": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/corpus",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-1a2b3c4d5e6f47a8b9c0d1e2f3a4b5c6"
      }
    },
    "rag-ledger": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/ledger",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-1a2b3c4d5e6f47a8b9c0d1e2f3a4b5c6"
      }
    },
    "rag-corpus-ws-9f8e7d6c5b4a43210fedcba987654321": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/corpus",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-9f8e7d6c5b4a43210fedcba987654321"
      }
    },
    "rag-ledger-ws-9f8e7d6c5b4a43210fedcba987654321": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/ledger",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-9f8e7d6c5b4a43210fedcba987654321"
      }
    }
  }
}

The agent sees each pair as separate tools, for example search_corpus on rag-corpus and search_corpus on rag-corpus-ws-9f8e…. Tell it which server covers which namespace in your agent instructions.

• Keep rag-corpus and rag-ledger as they are. Agent instructions refer to the tools by these names.
• You can rename the other servers to something readable, such as rag-corpus-research, as long as your agent instructions use the same names. The header, not the server name, decides the namespace.
• If an agent works in only one namespace, and it isn't your oldest, you can rename its servers to rag-corpus and rag-ledger. Instructions written for those names then work unchanged.

Delete a namespace

You need the Owner or Admin role.

1. Open Namespaces.
2. In the namespace's row, select the trash icon, Delete this namespace and everything in it.
3. Read the warning. It lists what will go: the namespace's sources, every vector indexed into it, and its ledger topics.
4. Type the namespace's name exactly, and select Delete namespace.

What happens next:

• At once, no key, search or console page reaches the namespace. Agents configured with its id get "no grant for namespace …".
• Its sources, index and ledger topics are removed in the background.
• Its id is never used again.

Deleting a namespace can't be undone

It deletes the namespace's ledger topics along with everything else. The ledger is the one part of Workstate that exists nowhere else, so be sure nobody still needs those topics.

On some deployments, deleting namespaces is switched off. The console then shows "deleting a workspace is not enabled on this deployment", and nothing is deleted.

Ways to split your namespaces

• One per client, so each client's material stays apart. See One namespace per client.
• One per sensitive area, such as HR or legal, so only the people who need it have access.
• One per team, when teams rarely need each other's material.

There are no per-document permissions inside a namespace. If some material should not be seen by everyone who has access to a namespace, put it in a separate one.

Related

• Namespaces
• One namespace per client
• API keys
• Roles