On this page
Inspect and maintain a corpus¶
Inspect text and passages¶
Filter files by name, status or type in Documents. An indexed file must also be active to appear in search. Actions on grouped copies use the selected copy’s UUID.
REST paths below share the prefix /api/v1/spaces/{space_id}.
GET /documentsreturns status and chunk count. Usenamefor case-insensitive substring matching,statusorcontent_typeto filter, andpageandpage_sizeto paginate.GET /documents/{document_id}returns details.extracted_char_countcounts Unicode code points before chunking, including whitespace.nullmeans unknown. Zero means extraction returned empty text.GET /documents/{document_id}/downloaddownloads the original.GET /chunks?document_id={document_id}lists canonical chunks in cut order. Filter their text withq. UseGET /chunks/{chunk_id}for text, metadata and available context, orGET /chunks/sizesto check passage lengths.
Inspect the embedding map¶
Open Data → Embedding map. Each dot is a chunk and each colour is a document. Select a dot to read the text. The map approximates distances by projecting dense vectors onto two dimensions with PCA.
Enter a query and select Highlight to see the current pipeline’s matches. Show on the map in a source card starts a new search with the question alone. Check the source card for the exact citation. Clear the query to remove highlights.
The owner can select Build the map when no map exists. While the job
runs, the page polls for status. The worker reads exported vectors or
re-embeds the available leaf chunks and saves their positions. The
fallback can incur provider charges and only approximates late-chunking
vectors. If the map uses saved positions, rebuild via
POST /chunk-map/build to include newer chunks.
GET /chunk-maprequires read access (API key scoperead). Status isabsent,buildingorready. A ready map returnspointswithchunk_id,document_id,xandy. To getmatched_chunk_ids, sendqueryand optionallytop_k(default 5, range 1–20). Query limits. A query can call models configured for retrieval. If it returns409because the required LLM is missing, retry without it. If the map alone returns409because vectors are unavailable, rebuild the map.POST /chunk-map/buildrequires write access (scopewrite) and an empty body. It returns202 Acceptedwithdocument_countandestimated_seconds, which may benull. A repeat request while a build runs returnsenqueued: false. Poll the read endpoint.POST /chunk-map/give-uprequires the same access and an empty body. Use it only after confirming a lost delivery. It releases a build the worker has yet to start and returnsreleasedandstatus.
Map read · Build request · Release a stranded build · Vector export and re-embedding
Replace, reindex or remove a document¶
Edit metadata. Send
PATCH /documents/{document_id}with{"metadata": {...}}. Include any fields you want to keep. This replaces the metadata object without recutting or re-embedding the file.Replace an original in managed storage. Read
accepted_revision_idandintent_versionusingGET /documents/{document_id}. Send a multipart file toPOST /documents/{document_id}/originalwith query parametersintent=replace, UUIDcommand_id, booleanuse_llm,expected_intent_versionand, if accepted,expected_revision_id. Stale expectations are rejected. For replayable creation, use an unused document UUID andintent=create. Omit both expectations. When the outcome is unknown, retry with identical content and the same command UUID.Reindex, deactivate or activate in managed storage. In Documents, open the file’s actions. For REST, send
POST /documents/{document_id}/{reindex|deactivate|activate}with{"command_id":"<UUID>"}. Reindex updates the cut and indexes. Deactivate removes the document from search and retains the original. Activate publishes a searchable cut.Remove a document. Send
DELETE /documents/{document_id}.204 No Contentmeans removal was accepted. The document is hidden immediately and physical cleanup runs in the background.X-Document-Operation-Ididentifies the retained operation. In attached storage, removal is limited to entries ContextBase owns. See Connections and storage.
Poll GET /document-operations/{operation_id} during
awaiting_original, queued, running or publishing.
Stop on succeeded, failed or cancelled. On failure, inspect
the operation and document before retrying. Search may still use the
previously accepted revision while its replacement is pending.
Choose and register an embedding model¶
Bind an embedding model when you create the space. The model and index must use the same vector dimensions. For an attached collection, choose a model and query settings compatible with its stored vectors. To change vector dimensions or semantics, create a space with the new model and load the corpus again.
List available models with GET /api/v1/embedding-models. See
GET /api/v1/embedding-models/catalog for registration settings. Use
local registration for models run by the installation. For a remote
OpenAI-compatible service, supply the model ID,
dimension and base URL before /embeddings. The service receives a
test embedding request on registration. If set, params.dimensions
must equal the registered dim. Keep the API key secret.
Update a model you registered via PUT /api/v1/embedding-models/{id}.
While a Space is bound to the model, only these may change: api_key,
embed_batch_size, max_concurrent_requests, max_retries,
max_tokens_per_request, price_per_million_tokens, and timeout.
The existing vectors remain valid.
For other settings, 409 Conflict lists the bound spaces.
Before a bulk upload, check preflight and Connections and storage.
The pgvector HNSW index supports at most 2,000 dimensions for the vector
type used here.
HNSW dimension limit.
Use embed_batch_size to balance throughput and memory.
Apply a pipeline change¶
Install jq and use an owner API key with manage scope.
Read the full config from GET /api/v1/spaces/{space_id}, change the
chunker and validate the complete JSON. This example sets a 384-token
budget with 48 tokens of overlap.
space="${BASE_URL}/api/v1/spaces/${SPACE_ID}"
curl --fail-with-body -sS -H "X-API-Key: ${CONTEXTBASE_API_KEY}" "$space" |
jq '.config | .chunk = {"node":"fixed","params":{"chunk_size":384,"chunk_overlap":48}}' > proposed-pipeline.json
curl --fail-with-body -sS -H "X-API-Key: ${CONTEXTBASE_API_KEY}" \
-H 'Content-Type: application/json' --data-binary @proposed-pipeline.json \
"$space/config/validate"
Validation reports errors, rebuild work and its cost estimate.
After review, send the same full JSON to PUT /config under the space URL.
Query-only changes can apply immediately.
For a managed rebuild, poll
GET /config/status. Checkrebuilding,stale,rebuild_failedand the processed/failed counts. Test search when the rebuild finishes. Depending on the change, the job refreshes representations or recuts the corpus.For an attached rebuild, check the space’s storage-index state as it processes external data.
Send POST /config/reindex to recut an eligible corpus with saved
settings, or POST /config/recheck to check resources without applying
changes.
Filter by document metadata¶
As the owner, send PUT /metadata-schema with the complete schema.
Each item in fields has name, field_type and optional
indexed (default true). Types are string, string_list,
number and boolean. Use a number for a year and a consistent
ISO format for dates stored as strings.
Document writes validate all declared fields, including unindexed ones.
Only declared, indexed fields are available for filters. Others can be
stored in metadata. On 202 Accepted, wait for the background metadata
update if the indexed fields changed. The schema update skips validation
of existing uploads. A document metadata patch keeps its original and cut.
In supported modes, metadata_filter selects candidates before
ranking. Join conditions and subgroups with all or any.
Operators depend on field type. Use eq for equality, one_of
for a value in a set, or contains for an element in a list field.
Unsupported query modes reject the filter.
After declaring year as a number, send this search body.
{
"query": "When are travel requests due?",
"metadata_filter": {
"join": "all",
"conditions": [{"field": "year", "operator": "eq", "value": 2026}]
}
}