On this page

Processing and indexing

Upload your first document

  1. Open a space where you are an editor or owner. In Documents, click Choose files and upload a UTF-8 text or Markdown file. For PDF, Office files or scans, set up the Extractor first.

  2. Wait for Indexed and check that the document is active. Search for a phrase from the file and open the matching passage.

  3. If the phrase is missing, inspect the extracted passages. Check extraction and chunk boundaries before changing retrieval settings.

The Documents page showing the Next Product Lab sample guide as Indexed.

Check Status and Chunks for the indexed sample guide.

What gets indexed

  1. Original file

    ContextBase keeps the uploaded file for download and reprocessing.

  2. Extraction

    The extractor reads text and any available structure, such as sections and tables.

  3. Chunking

    The chunker divides the extracted text into passages.

  4. Indexing

    The space builds the representations its retrievers use.

Upload and search via REST

Set BASE_URL to the instance URL and SPACE_ID to the space UUID. Set CONTEXTBASE_API_KEY in a trusted client or service. Use a key with write access for upload and search access for the second request.

printf '%s\n' 'Travel requests are due ten working days before departure.' > travel.txt
curl --fail-with-body -sS \
  -H "X-API-Key: ${CONTEXTBASE_API_KEY}" \
  -F 'file=@travel.txt;type=text/plain' \
  -F 'name=Travel policy' \
  -F 'metadata={"department":"operations","year":2026}' \
  "${BASE_URL}/api/v1/spaces/${SPACE_ID}/documents"

Upload runs inline. Read status and is_active in the 201 Created response and keep id for inspection or download. If name is omitted, the filename is used. Send metadata as one JSON object, preserving value types such as 2026 versus "2026". Upload endpoint

Search the same space.

curl --fail-with-body -sS \
  -H "X-API-Key: ${CONTEXTBASE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"query":"When are travel requests due?","top_k":3}' \
  "${BASE_URL}/api/v1/spaces/${SPACE_ID}/search"

For a generated answer, see Search and answers.

Import an archive

In a space with managed storage, choose how to import a ZIP, TAR.GZ, TGZ, RAR or 7Z archive in Documents:

  • One document combines the extracted text from readable entries.

  • Separate documents gives each admitted entry its own document record and indexing operation. Check each result, since the archive can contain skipped or failed entries.

The managed REST import is POST /api/v1/spaces/{space_id}/documents/archive with the archive in a multipart file part and query parameters command_id (UUID) and mode=combined or mode=separate. The 202 Accepted response contains items with each entry’s status and operation ID where applicable. Keep the same command UUID, file, mode and other options when retrying an unanswered submission. The archive reader enforces limits on expanded size and entries, and rejects unsafe paths. The document admission limit applies to the uploaded archive itself. For attached storage, the browser uses the combined ordinary upload path and that storage’s write rules apply. Archive import

Common upload results

  • 400: check the named field, including metadata types and extraction preferences.

  • 403: use the editor or owner role for uploading.

  • 413: check DOCUMENT_MAX_UPLOAD_BYTES (100 MiB by default) and the gateway’s request-body limit. Upload limit.

  • 409 or 428 with attached storage: check the reason and verify mapping, supported settings and corpus confirmation in Connections and storage.

  • Uploaded (uploaded): the file is stored. If no passages are searchable, check its encoding, format support and OCR.

ContextBase0.1.0

Search the documentation