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 /documents returns status and chunk count. Use name for case-insensitive substring matching, status or content_type to filter, and page and page_size to paginate.

  • GET /documents/{document_id} returns details. extracted_char_count counts Unicode code points before chunking, including whitespace. null means unknown. Zero means extraction returned empty text.

  • GET /documents/{document_id}/download downloads the original.

  • GET /chunks?document_id={document_id} lists canonical chunks in cut order. Filter their text with q. Use GET /chunks/{chunk_id} for text, metadata and available context, or GET /chunks/sizes to check passage lengths.

Document details · Chunk collection · Chunk details

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-map requires read access (API key scope read). Status is absent, building or ready. A ready map returns points with chunk_id, document_id, x and y. To get matched_chunk_ids, send query and optionally top_k (default 5, range 1–20). Query limits. A query can call models configured for retrieval. If it returns 409 because the required LLM is missing, retry without it. If the map alone returns 409 because vectors are unavailable, rebuild the map.

  • POST /chunk-map/build requires write access (scope write) and an empty body. It returns 202 Accepted with document_count and estimated_seconds, which may be null. A repeat request while a build runs returns enqueued: false. Poll the read endpoint.

  • POST /chunk-map/give-up requires 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 returns released and status.

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_id and intent_version using GET /documents/{document_id}. Send a multipart file to POST /documents/{document_id}/original with query parameters intent=replace, UUID command_id, boolean use_llm, expected_intent_version and, if accepted, expected_revision_id. Stale expectations are rejected. For replayable creation, use an unused document UUID and intent=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 Content means removal was accepted. The document is hidden immediately and physical cleanup runs in the background. X-Document-Operation-Id identifies 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.

Original and concurrency contract · Asynchronous progress

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.

Model catalog · Embedding checks · Indexing batches

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. Check rebuilding, stale, rebuild_failed and 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.

Configuration apply · Rebuild status

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}]
  }
}

Metadata schema · Filter groups

ContextBase0.1.0

Search the documentation