Knowledge bases

POST/DELETE /admin/kb/{kb_id}/... — workspace-scoped RAG knowledge bases. Each KB is a collection in the configured VectorStore (lancedb / pgvector / qdrant / milvus) namespaced by {workspace}:{kb_id} so two workspaces with the same kb_id never collide.

KBs are the input side of the RAG path: documents are ingested, chunked, embedded via the configured ServingEngine.embed, and indexed in the vector store. At chat time the firstparty gateway can attach a KB to a completion via the bigwave_kb_id extension field (PRD 05 §"RAG"); the matching chunks land in the system prompt as citation context.

Endpoints

Method	Path	Auth	Summary
POST	/admin/kb/{kb_id}/documents	Bearer + workspace	Ingest one or more documents; auto-chunk + embed + index.
POST	/admin/kb/{kb_id}/query	Bearer + workspace	Vector-similarity query; returns top-k chunks.
DELETE	/admin/kb/{kb_id}/documents/{doc_id}	Bearer + workspace	Delete every chunk derived from one document.

The KB itself is created lazily on the first ingest call against a new kb_id; there's no separate "create KB" endpoint.

POST /admin/kb/{kb_id}/documents

Ingest a batch. Request body matches IngestRequest from packages/data/admin_routes.py:62:

{
  "docs": [
    { "doc_id": "policy-v3-section-4", "text": "..." },
    { "doc_id": "policy-v3-section-5", "text": "..." }
  ]
}

Each document is chunked by the configured Chunker (packages/data/chunker.py), embedded, and upserted into the vector store under the {workspace}:{kb_id} collection.

curl -X POST https://your-host/admin/kb/policies-v3/documents \
  -H "Authorization: Bearer $BIGWAVE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"docs":[{"doc_id":"sec-4","text":"..."}]}'

POST /admin/kb/{kb_id}/query

Vector-similarity query. Body matches QueryRequest (packages/data/admin_routes.py:68):

{
  "text": "What is the refund policy?",
  "k": 4,
  "filters": { "section": "refunds" }
}

• text — the query string; embedded with the same model the ingestion path used.
• k — number of chunks to return (default 4).
• filters — optional metadata filter applied at the vector-store layer. Backend-specific (qdrant payload filters, lancedb where clauses, pgvector JSONB matches).

Response: list of VectorHit objects (chunk id, score, text, metadata). Use this directly from your application, OR rely on the gateway's bigwave_kb_id chat-completion extension to do the same retrieval automatically.

DELETE /admin/kb/{kb_id}/documents/{doc_id}

Removes every chunk derived from the source document. Idempotent: 404 on unknown doc id. Use when a document is retracted (legal takedown, source error correction).

Operator notes

• Workspace fence. Collection names include the workspace prefix, so kb_id="policies" in workspace A and workspace B are separate physical collections. Cross-tenant access is impossible even at the vector-store layer.
• No KB lifecycle endpoint in v0. KBs come into being on the first ingest and disappear when their last document is deleted. Explicit "create KB" / "list KBs" / "delete KB" endpoints are roadmap.
• Embedder mismatch is fatal. Documents ingested under one embedding model and queried under another will return garbage scores. If you change ServingEngine.embed configuration, reingest.
• Vector-store-specific filter syntax. The filters object is passed through to the adapter; the operator is responsible for using shapes their backend understands. See /admin/adapters for the active vector-store adapter.
• Errors:
  • 400 — malformed body, unsupported filter shape.
  • 401 — missing bearer.
  • 404 — unknown kb_id (query / delete) or doc_id (delete).
  • 413 — document batch exceeds the size cap.

Related

• /how-to/09-knowledge — operator runbook.
• /admin/uploads — adjacent file-upload surface used by chat completions for attachment extraction (different ingestion path, no vector index).
• /admin/adapters — the active vector-store adapter selection.
• PRD 05 §RAG — the contract this surface implements.