Create a Knowledge Base

A knowledge base must belong to a team. Two decisions are hard to reverse: the embedding model fixes the vector dimension (it cannot be changed once documents are processed), and visibility decides who can read it without a share. The name must be unique within the team.

Permissions and visibility

Visibility is set in the create/edit dialog:

Cross-team access is only ever granted through a share and is always read-only — see “Cross-team sharing (read-only)” below.

Creating a knowledge base

1. Go to Knowledge Bases and select Create Knowledge Base.
2. Fill in the basics:
   • Name: 1-100 characters, unique within the team; a duplicate returns kb_name_exists.
   • Description: up to 500 characters describing purpose and scope.
   • Team: the current team (the admin dashboard form can target another team).
3. Select models:
   • Embedding Model: an embedding model authorized for the team. embedding_model_id cannot be changed after creation.
   • Rerank Model: optional; once bound, recall results can be re-scored during retrieval.
4. Configure chunking and reranking:
   • Chunk Size chunk_size: default 1000 characters, minimum 100 (UI suggests a maximum of 2000).
   • Chunk Overlap chunk_overlap: default 100 characters, minimum 0 (UI suggests a maximum of 500).
   • Custom Separator: escape sequences such as \n\n are allowed and act as a hard split boundary.
   • Enable Reranking: on by default; Rerank Candidate Pool defaults to 10 (1-100); Rerank Score Threshold defaults to empty (0-1).
5. Choose visibility (private or team).
6. Click Create Knowledge Base and open the detail page; confirm the status is Active.

When editing an existing knowledge base the dialog also offers an Enable Knowledge Base switch (turning it off sets archived, and archived knowledge bases are not searched).

Models and vector dimensions

Embedding model

A platform model with model_type = embedding. It appears in the create form only after being granted to the team through model authorization. A knowledge base references exactly one embedding model; without an available model, neither document processing nor retrieval can run.

Vector dimensions

embedding_dimension is written and frozen when the first batch of documents finishes vectorization. From then on:

• documents with a matching dimension are indexed normally;
• vectors with a mismatched dimension raise a dimension mismatch error, and retrieval reports the configuration_mismatch category so you can verify the model and index dimension;
• changing the embedding model never rebuilds the index automatically — create a new knowledge base or run a full reprocessing flow.

Chunking and retrieval settings

For the character semantics of chunking, the Markdown versus plain-text difference, preview, and failure retries, see Chunking and Document Processing.

Cross-team sharing (read-only)

Sharing gives another team read and retrieval access to a knowledge base, but no editing rights. It is the only form of cross-team access.

Steps

1. In the Knowledge Bases list, hover a card, open the ⋯ menu, and choose Share.
   • The entry is only shown for knowledge bases your own team owns, and only to team owners/admins.
2. In the Share dialog, select a team.
   • The list comes from the teams you belong to and automatically excludes the current team and teams already shared with.
   • The Permission Level offers only Read Only and cannot be changed.
3. Click Share. The entry appears with a read-only badge and a "Shared by …" note.
4. To revoke, click the delete icon on that entry under Shared With and confirm; the knowledge base disappears from the receiving team's list immediately.

Rules and failure reasons

After sharing, both sides show a marker in their lists:

• Receiver: a From + team name badge, and every write entry point is disabled on the detail page (is_owned = false).
• Owner: a Shared with N teams badge, with N coming from shared_with_count.

Sharing through the API

# Share with another team (read_only is the only valid permission value)
curl -X POST "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/share" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"team_id": "TARGET_TEAM_UUID", "permission": "read_only"}'

# List the teams it is shared with (owning-team members only)
curl "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/shares" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Revoke a share
curl -X DELETE "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/share/$TARGET_TEAM_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

On the receiving side, GET /api/v1/knowledge-bases accepts include_shared (default true) and own_only (default false); set include_shared=false or own_only=true to see only your own teams' knowledge bases.

Document management

Document management covers upload, processing, reprocessing, and deletion; the detailed steps are in Import Documents and Chunking and Document Processing.

Statistics

The knowledge base detail page shows statistic cards at the top (documents, chunks, tokens, and per-status counts); Hit Testing in the dropdown opens the retrieval lab.

GET /api/v1/knowledge-bases/{kb_id}/stats returns:

• document_count (recomputed from actual documents, not the cached value)
• total_chunks, total_tokens (aggregated from documents and written back to the KB cache fields)
• documents_by_status, documents_by_type
• embedding_dimension and embedding_stats

Troubleshooting

Document processing failed

1. Confirm the format is supported, the file is not corrupted, and it is within the size limit.
2. Open the document detail to read the error and identify whether extraction, chunking, or embedding failed.
3. Common causes and fixes:

No results or irrelevant results

1. Confirm the documents are completed.
2. Use Hit Testing to verify scores: with zero results, lower score_threshold first, then switch search mode.
3. Check whether an Agent overrides the knowledge base settings (retrieval_top_k, score_threshold, and search_mode on the association).
4. Check that the vector store and pg_search are healthy; reprocess documents if needed.

Cost or performance anomalies

• High cost: avoid unnecessary reprocessing, tune chunking (larger chunks, less overlap), switch to a cheaper embedding model, and delete redundant documents.
• Slow retrieval: lower top_k, disable reranking for simple queries, narrow the document scope, and check vector store resources.

Best practices

• ✅ Name knowledge bases by content scope; avoid names like "Docs" or "Materials" that carry no information.
• ✅ Get one representative document working with the defaults (1000/100), then compare adjustments with hit testing.
• ✅ Clean up stale documents regularly; duplicate content competes with itself in the ranking.
• ✅ Keep private knowledge bases for personal drafts; use team visibility for anything the team shares.
• ❌ Do not expect to "add metadata" to improve retrieval — metadata is generated by the processing pipeline and has no editing entry point.
• ❌ Do not replace the embedding model in production, and do not scale chunk size up without validating retrieval first.

API access

Manage knowledge bases through the API; the endpoint list is in the Knowledge Base API. Knowledge base endpoints accept only a signed-in user's JWT session (Authorization: Bearer <ACCESS_TOKEN>) and do not accept a clou_ API key.

# List knowledge bases — supports team_id, search, status, own_only, include_shared
kbs = api.get("/api/v1/knowledge-bases", params={"team_id": "team-123", "include_shared": True})

# Create a knowledge base for a team
kb = api.post("/api/v1/knowledge-bases", json={
    "name": "Product Docs",
    "team_id": "team-123",
    "embedding_model_id": "model-456",
    "visibility": "team",
    "settings": {"chunk_size": 1000, "chunk_overlap": 100, "rerank_enabled": True}
})

# Upload a document
with open("document.pdf", "rb") as f:
    doc = api.post(
        f"/api/v1/knowledge-bases/{kb_id}/documents/upload",
        files={"file": f}
    )

# Search a knowledge base
results = api.post(f"/api/v1/knowledge-bases/{kb_id}/search", json={
    "query": "How to reset password?",
    "top_k": 5
})

Document processing API:

Related pages

• Import Documents — upload, URL import, and failure retries
• Chunking and Document Processing — preview, process, and edit chunks
• Browsing Documents & Metadata — sharing badges and system fields
• Retrieval & Quality Tuning — the retrieval lab and diagnostics
• Knowledge Base settings reference — every field and limit