On this page
Spaces and access¶
Create and check a space¶
Open Spaces → Create space. Your account needs permission to create spaces. Name the space, then choose an embedding model, a storage backend and a pipeline.
Resolve blocking findings in the validation report and save. Your account becomes the direct owner.
Upload a sample document and search for a phrase from it. Installation and quickstart
POST /api/v1/spaces/ returns 201 Created. Set name to
1–255 characters. embedding_model_id and vector_backend_id may refer
to installation-shared entries or your own entries. Omit either ID to use
the installation default. Request fields
Omit config for fixed-size chunks, dense retrieval, identity fusion
and an LLM generator. For search without generation, choose a search preset
or set generate to null in the pipeline.
Send the same body to POST /api/v1/spaces/validate to get the verdict
and findings without creating a space. A valid request returns 200 even
if the verdict blocks creation.
If creation returns
422, fix the structural or consistency error in the report.If creation returns
409withblocked_by_probe_only, check each failing resource’s reachability and credentials. Useforcein the create body only to proceed despite failed live checks.
Choose who can do what¶
Installation permission
Allows the account to create spaces.
Space role
Controls what the account can do in one space.
Space role |
Typical use |
|---|---|
Viewer ( |
Read documents and run search or ask questions. |
Editor ( |
Do the same and add, edit or remove documents where storage permits. |
Owner ( |
Configure the space, manage its direct participants and delete it. |
The highest role across direct assignments and groups wins. Removing direct access leaves group access in place. Keep at least one direct owner, even if a group has the owner role. Installation administrators need a space role to access its contents. Use separate spaces and storage targets for separate audiences, especially with an attached index.
Owners can open usage analytics. Reading stored query and answer-check text requires a separate grant.
Give a person access¶
As a space owner, open Participants, enter the email address and select a role. Active accounts get access immediately. For a new or pending account, copy the invitation link and send it to the participant so they can set a password. Enter the same email again to reissue a lost invitation.
Change or remove direct access in the participant list. If access persists, check Access through groups.
List or add direct members at /api/v1/spaces/{space_id}/members.
Use /members/{user_id} under the same space to change a role or remove
direct membership. The membership API requires an interactive session.
Give a team or a group permission¶
As an installation administrator, open Groups, create a local group, add accounts and assign its role separately in each space. Grant Permission to create spaces separately. Changes take effect on the next request alongside the person’s other assignments.
All users includes all active accounts. Only the superadministrator created during setup can manage membership in Administrators. Before deleting a local group, remove its installation grants and space roles. Check the group audit log for membership and assignment changes.
Give an application an API key¶
Open Access and keys as the account the application will use. Create a key and grant the smallest required scope in each space.
API key scope |
What it opens |
|---|---|
|
Read a scoped space, retrieve passages and ask questions. |
|
Also write documents in the space. |
|
Also manage its pipeline, inspections and evaluations, and delete the space. |
A key’s access is limited by its owner’s current role in the space. Only
a space owner can grant manage. Use generic for server-to-server
calls. An mcp key needs at least one explicit space grant and is capped
at write. A key without space grants lists no spaces. If the key’s owner
has permission to create spaces, a successful API creation grants that key
access to the new space up to the limit of its purpose.
Copy the key when it appears, store it on the application server, and send
it in X-API-Key. Open Access and keys to check its prefix, scopes,
expiry, last use or state, or to revoke it. Changing membership, creating
keys and editing space settings such as the LLM require an interactive
session. Integrate ContextBase · Connect an MCP client
Check access or remove a space¶
401. Check the key status, required credential type and request headers.403. Check the installation grant for creation, or the effective space role for other actions.404. For an existing space, check direct roles, group roles and key scopes. On creation, check the backend and embedding model IDs too.
Set extraction, the LLM and outbound connections in the space settings. Edit search in Pipeline. The space binds its embedding model and storage at creation. To switch models, create a new space and reindex the documents there. Match the original model when attaching existing vectors.
Delete a space in its settings or call DELETE /api/v1/spaces/{id}.
After 204 the space is unavailable immediately. Workers remove its
documents, retained originals and managed indexes in the background.
An attached store preserves the original corpus and requires a decision
about rows added by the space. Connections and storage