On this page

Spaces and access

Create and check a space

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

  2. Resolve blocking findings in the validation report and save. Your account becomes the direct owner.

  3. 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 409 with blocked_by_probe_only, check each failing resource’s reachability and credentials. Use force in 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 (viewer)

Read documents and run search or ask questions.

Editor (editor)

Do the same and add, edit or remove documents where storage permits.

Owner (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

Read a scoped space, retrieve passages and ask questions.

write

Also write documents in the space.

manage

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

CreateSpace, access policy and API key scope levels.

ContextBase0.1.0

Search the documentation