On this page

Use ContextBase from an application

1. Give the application access to one Space

In Access and keys, create a Regular key for the Space with the indexed Next Product Lab sample guide from Installation and quickstart. Select Read, set an expiry and save the full key in your secret store. The key list shows its prefix and status.

Set these variables in your backend or local terminal.

  • CONTEXTBASE_BASE_URL — http://localhost:13000 for the local setup, or the HTTPS URL of your installation.

  • CONTEXTBASE_SPACE_ID — UUID from the Space URL or from GET /api/v1/spaces/ with the scoped key.

  • CONTEXTBASE_API_KEY — full key for the X-API-Key request header. Store it on the server side of your application.

2. Retrieve the supporting passages

curl --fail-with-body "$CONTEXTBASE_BASE_URL/api/v1/spaces/$CONTEXTBASE_SPACE_ID/search" \
  -H "X-API-Key: $CONTEXTBASE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"query":"How early should I prepare draft release notes before the demo?","top_k":5}'

Find the release notes passage in sources[].text. The sample requires at least two working days before the demo.

Matching passages

Use POST /search and display sources[] in rank order. Choose LLM-free transformations and rerankers for a request that makes no LLM calls.

Written answer with citations

Use POST /query or POST /query/stream. Render answer and sources[] separately. In a stream, use the final done event.

Search parameters

  • top_k applies to search, query and query/stream. The range is 1–20 and the default is 5.

  • metadata_filter filters by fields declared on the Space. Check restrictions by query mode.

  • rrf_k overrides the reciprocal-rank constant for search when the pipeline supports it. Check the effective setting in retrieval_receipt.

3. Request a written answer and display its evidence

Configure a model and enable a generator on the Space.

curl --fail-with-body "$CONTEXTBASE_BASE_URL/api/v1/spaces/$CONTEXTBASE_SPACE_ID/query" \
  -H "X-API-Key: $CONTEXTBASE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"query":"How early should I prepare draft release notes before the demo?","top_k":5}'

Check that the citations support the two-working-day rule. Generated wording can vary. If outcome is blocked, the pipeline withheld the candidate answer.

Use these source fields for citations.

  • text is the matched excerpt. parent_text may supply a broader passage for grounding. graph_context may supply graph summaries and relations.

  • locator identifies a verified location when available. It includes document_id, document name, section path and Unicode character offsets start (inclusive) and end (exclusive). Page and label are optional. A parent passage can have its own parent_locator.

  • bibliography describes a canonical document when available. Display the owner’s URL as a reference. Use authenticated document download for a retained original.

Link to a canonical chunk with GET /api/v1/spaces/{space_id}/chunks/{chunk_id}. If an attached-store excerpt has no canonical chunk, keep the excerpt visible. Treat IDs as opaque. An ID can stop resolving after a document changes.

Feedback

When present, query_id identifies the query record. The original asker can rate their logged answer using a browser session or a key with read on the Space. Send the rating to PUT /api/v1/spaces/{space_id}/queries/{query_id}/feedback.

4. Show progress during generation

POST /api/v1/spaces/{space_id}/query/stream accepts the query body and returns Server-Sent Events. Use either SDK or curl -N to consume the POST response. Handle HTTP errors before opening the stream.

Event

What to do

stage

Show the stage using stage, label_key, icon and phase.

check

Track checks by node_id, attempt_id and phase. Use the verdict and action when present.

token

Append delta to provisional text. Some paths such as agent graphs send a complete answer without tokens.

done

Replace provisional output with the final answer and sources. Check outcome for a blocked answer.

error

End the progress display. Show detail and branch on reason. An in-stream failure ends with this event.

See the event encoder and SDK examples.

If search or generation fails

  • 401 — check the full X-API-Key, its expiry and the installation.

  • 404 — check the Space UUID and the key’s grant. A Space without access can also return 404.

  • 409 — read reason for index readiness, a missing generator model, or a filter incompatible with the query mode.

  • 502 — use detail to identify the provider, vector store or other upstream service to check.

Issue keys from provisioning code

With a signed-in user session, call POST /api/v1/auth/api-keys/.

{
  "name": "Next Product Lab demo app",
  "purpose": "generic",
  "scopes": [{"space": "SPACE_UUID", "level": "read"}]
}

Use write for uploads and manage for owner-only pipeline and evaluation operations that accept keys. The scope and the key owner’s current role both apply. Issue keys under a user session and manage membership and installation settings in the UI. See Spaces and access.

ContextBase0.1.0

Search the documentation