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:13000for the local setup, or the HTTPS URL of your installation.CONTEXTBASE_SPACE_ID— UUID from the Space URL or fromGET /api/v1/spaces/with the scoped key.CONTEXTBASE_API_KEY— full key for theX-API-Keyrequest 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_kapplies tosearch,queryandquery/stream. The range is 1–20 and the default is 5.metadata_filterfilters by fields declared on the Space. Check restrictions by query mode.rrf_koverrides the reciprocal-rank constant forsearchwhen the pipeline supports it. Check the effective setting inretrieval_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.
textis the matched excerpt.parent_textmay supply a broader passage for grounding.graph_contextmay supply graph summaries and relations.locatoridentifies a verified location when available. It includesdocument_id, document name, section path and Unicode character offsetsstart(inclusive) andend(exclusive). Page and label are optional. A parent passage can have its ownparent_locator.bibliographydescribes 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 |
|---|---|
|
Show the stage using |
|
Track checks by |
|
Append |
|
Replace provisional output with the final |
|
End the progress display. Show |
See the event encoder and SDK examples.
If search or generation fails¶
401— check the fullX-API-Key, its expiry and the installation.404— check the Space UUID and the key’s grant. A Space without access can also return404.409— readreasonfor index readiness, a missing generator model, or a filter incompatible with the query mode.502— usedetailto 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.