Workstate Docs

Namespaces ​

A namespace is a separate index inside your Workstate account. Each namespace has its own sources, its own search results and its own ledger. The console calls it a namespace, and the API calls it a workspace.

Use namespaces to keep apart what should stay apart: teams, clients or sensitive material.

What a namespace holds ​

  • Sources, and everything indexed from them. Each source belongs to one namespace.
  • Ledger topics. Topic ids are numbered per namespace, so payments-0001 in one namespace and payments-0001 in another are different topics.
  • Nothing from other namespaces. A search never returns another namespace's content, and a topic id means nothing outside its own namespace.

Names and ids ​

A person names a namespace, for example "Research". Workstate gives it an id: ws- followed by 32 hexadecimal characters. Some older namespaces have short ids, such as default.

Agents use the id, not the name. The Namespaces page and the namespace switcher show both, and the Namespaces page has a button to copy the id.

A new account starts with one namespace, called Personal.

How a request picks its namespace ​

Every agent request is answered from one namespace:

  • Named: the request names a namespace id in the X-RAG-Namespace header. Workstate checks it against the namespaces the key's owner can reach. If they cannot reach it, the request is refused with no grant for namespace. It is never answered from another namespace instead.
  • Not named: the request is answered from the person's oldest namespace, the first one created among those they can reach. Which one that is changes if they are given an older namespace, or their oldest is deleted. Anyone who can reach more than one namespace should always send the header.

The configuration on the API keys page sets the header for you, for the namespace selected in the switcher. For your oldest namespace, the servers are named rag-corpus and rag-ledger. For any other, the names end in its id, so the configurations for several namespaces fit in one file.

In the console ​

The switcher at the top of the sidebar selects the namespace that the console shows. Overview, Search, Ledger, Sources and Repositories show only that namespace, and name it. New sources are added to it. The console remembers your choice in that browser.

Who can reach a namespace ​

A person reaches a namespace only once it is granted to them:

  • When it is created, it is granted to the person who created it, and to every owner and admin of the account.
  • When someone is invited, the invitation grants the namespaces picked in it.
  • At any time, an owner or admin can give a person a namespace, or take it away, in the Namespaces column of the Team page. The change applies to the person's next request.

Owners and admins can give only the namespaces they reach themselves. See Permissions.

Creating and deleting namespaces ​

Owners and admins create namespaces, on the Namespaces page or with New namespace… in the switcher.

Deleting a namespace removes its sources, everything indexed from them, and its ledger topics. Keys lose access to it at once. Deletion cannot be undone, and the id is never used again. To confirm, you type the namespace's name. Some deployments turn deletion off, and the console then shows an error instead. See Managing namespaces.

Limits ​

  • No per-document permissions. Everyone who can reach a namespace sees everything in it. Keep sensitive material in a namespace of its own. See Permissions.
  • One namespace per request. To search two namespaces, make two requests, or register both pairs of servers.

Workstate is built by Nerdstorm Pty Ltd, Sydney.