Knowledge Base API

Knowledge base ingest and retrieval.

List Knowledge Bases

GET /v1/knowledge-bases?workspace_id=ws-001

Upload a Document

Single File

POST /v1/knowledge-bases/{id}/documents
Content-Type: multipart/form-data

file: <binary>
group: Public
metadata: {"author": "Alice", "category": "FAQ"}

Response:

{
  "document_id": "doc-001",
  "name": "FAQ.pdf",
  "size_bytes": 1024000,
  "status": "parsing",
  "created_at": "..."
}

Text

POST /v1/knowledge-bases/{id}/documents

{
  "type": "text",
  "name": "Return Policy",
  "content": "Our return policy...",
  "metadata": { "category": "FAQ" }
}

Status Query

GET /v1/documents/{document_id}

{
  "id": "doc-001",
  "status": "ready",
  "chunks_count": 47,
  "indexed_at": "..."
}

status values: uploading / parsing / chunking / embedding / ready / failed.

Search

POST /v1/knowledge-bases/{id}/search

{
  "query": "return policy",
  "top_k": 5,
  "filters": { "category": "FAQ" },
  "rerank": true
}

Response:

{
  "results": [
    {
      "chunk_id": "ch-001",
      "document_id": "doc-001",
      "document_name": "FAQ.pdf",
      "content": "We offer 7-day no-questions-asked returns...",
      "score": 0.87,
      "metadata": { "page": 3 }
    }
  ]
}

Delete a Document

DELETE /v1/documents/{document_id}

Re-Parse

POST /v1/documents/{document_id}/reparse

Useful for bulk re-parsing after changing the chunking strategy.

Anti-Patterns

Treating the search API as an LLM call — it returns retrieval results only, no generation. Use Agent for generation
Setting TopK to 100 — the LLM context cannot accommodate it; noise increases hallucination

API · Knowledge Base