Knowledge Bases

A Knowledge Base (KB) is the core organizational unit in the RAG API. It groups related documents together and defines the boundary for search queries.

Data Model

Account (tenant, acc_ prefix)
  └── Knowledge Base (query boundary, kb_ prefix)
        └── Document (uploaded file/text, doc_ prefix)
              └── Chunk (embedded segment, chk_ prefix)

• Account — Your tenant. One account per API key. All resources are isolated by account.
• Knowledge Base — A logical collection of documents. All search queries are scoped to a single KB. Use separate KBs for different use cases (e.g., “Product Docs”, “Support Articles”, “Legal Contracts”).
• Document — A file or text you upload. Processed automatically through the ingestion pipeline.
• Chunk — A segment of a document, typically ~500 tokens. Each chunk has an embedding vector used for search.

When to Create Multiple KBs

Use Case	Approach
Different content domains	Separate KBs (e.g., “Engineering Docs” vs “HR Policies”)
Multi-tenant app	One KB per customer/workspace
Dev/staging/prod content	Separate KBs per environment
Single product’s docs	One KB is sufficient

KB Lifecycle

1. Create — POST /v1/knowledge-bases with a name and optional description/metadata
2. Add documents — Upload files or ingest text into the KB
3. Search — Query the KB with natural language
4. Update — Change the name, description, or metadata via PATCH
5. Delete — Removes the KB and cascades to all documents and chunks

Caution

Deleting a knowledge base permanently removes all its documents and chunks. This cannot be undone.

ID Format

All resource IDs use a prefix followed by a nanoid:

Resource	Prefix	Example
Account	acc_	acc_a1b2c3d4e5
Knowledge Base	kb_	kb_x1y2z3w4v5
Document	doc_	doc_f6g7h8i9j0
Chunk	chk_	chk_k1l2m3n4o5

Metadata

Each KB supports an arbitrary metadata JSON object. Use it for tagging, categorization, or any key-value pairs your application needs:

{
  "name": "Q1 Reports",
  "metadata": {
    "team": "finance",
    "quarter": "Q1-2026",
    "confidential": true
  }
}

KB metadata is for your organizational use — it is not used in search filtering. For search filtering, use document metadata.