Documents & namespaces

A namespace groups the documents available to a question. Use one per collection or end customer, within the user who owns the API key.

Namespaces

Names contain 1–128 ASCII letters, digits, ., _, : or -. Surrounding whitespace is removed. Omitting a namespace uses default.

The first upload creates a namespace. Deleting its last file leaves an empty namespace; delete the namespace explicitly to remove it.

Wait for processing

An upload returns 202 and a file object in pending status. Poll GET /api/knowledge/files/{file_id} every few seconds. Files progress through extracting, structuring and indexing to ready; Markdown skips extraction and structuring.

If the status becomes failed, inspect the file's error, delete the file and upload it again to retry. Use a bounded polling loop rather than waiting forever. The walkthroughs allow three minutes for processing; larger documents may need a longer limit.

Wait for ready before relying on a document in an answer. Its passages may already be searchable during indexing, but complete document reading is available only after it is ready.

Formats and limits

Start with Markdown to try the API without document conversion. Supported ingestion formats are .md, .pdf, .docx, .pptx, .xlsx, .xlsm, .xls, .csv, .tsv, .txt, .json, .xml, .rtf, .xbrl, .ixbrl, .html, .htm, .jpg, .jpeg, .png, .tif, .tiff, .bmp, .gif and .webp.

Convert legacy .doc and .ppt files to .docx and .pptx first. Unsupported formats may fail during extraction.

The default file limit is 50 MB. Other storage and request limits are published in the reference limits table, alongside their error responses. An upload over the file limit returns 413; exceeding a storage quota returns 409.

Ask with the right scope

Each question covers one namespace, optionally restricted by file_ids. Questions have no conversation history: include the context needed for a follow-up in its prompt.

The agent searches and reads only those documents. It is instructed to answer from them and say when they do not cover the question. sources lists files it retrieved passages from; it may include a file the final answer did not use. Check the source documents when your application needs to verify a claim.

Clean up

The walkthroughs keep your uploaded file so you can ask more questions. To delete the entire quickstart namespace and its files, run this deliberately after you finish:

curl --fail-with-body --silent --show-error --request DELETE \
  --header "Authorization: Bearer $LAB0_API_KEY" \
  "$LAB0_BASE_URL/api/knowledge/namespaces/quickstart"

Deleting a namespace removes all of its files. To remove only one, use DELETE /api/knowledge/files/{file_id} instead. Both actions require a Read & write key.