// Search the RAG knowledge base via hybrid search (semantic + BM25). Use whenever answering technical questions that may be covered in your knowledge base — even if the user doesn't explicitly ask you to search. Also use when you need to verify claims or find up-to-date information.
| name | zeabur-rag-search |
| description | Search the RAG knowledge base via hybrid search (semantic + BM25). Use whenever answering technical questions that may be covered in your knowledge base — even if the user doesn't explicitly ask you to search. Also use when you need to verify claims or find up-to-date information. |
Search your knowledge base using hybrid retrieval (semantic + BM25 keyword).
Base URL: $ZEABUR_RAG_URL
Auth: Authorization: Bearer $RAG_API_KEY
curl -s -X POST "$ZEABUR_RAG_URL/api/query" \
-H "Authorization: Bearer $RAG_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "your question", "mode": "hybrid", "rag": false, "top_k": 5, "client": "claude-code"}'
| Parameter | Default | Description |
|---|---|---|
query | required | Search query (supports multilingual) |
mode | "hybrid" | "hybrid" (BM25 + semantic) or "semantic" |
top_k | 5 | Number of chunks to return |
rag | false | If true, also returns LLM-generated answer string |
keyword_weight | 0.25 | BM25 weight in hybrid mode |
semantic_weight | 0.75 | Semantic weight in hybrid mode |
decay | 180 | Temporal decay half-life in days (0 = off) |
stream | false | Stream the RAG answer (NDJSON) |
visibility | "public" | "public", "internal", or "all" — filters chunks by visibility |
client | "api" | Caller identifier for analytics (e.g. "claude-code", "web-ui", "mcp") |
Always pass client: "claude-code" when calling from Claude Code so queries are trackable in the dashboard.
Response includes chunks[] (each with id, title, answer, tags, similarity (relevance score), source, verified) and signal_id for linking feedback. Note: similarity is an RRF score in hybrid mode (~0–0.02) or cosine similarity in semantic mode (0–1). The scale depends on the search mode — do not compare values across modes.
rag: false when you only need raw chunks to read yourself — it's faster and cheaper.rag: true only when you want the service to generate a summarized answer.signal_id in the response can be passed to the feedback API to rate result quality.Contribute new verified knowledge to the RAG knowledge base. Use after you've solved a concrete problem, debugged a non-obvious issue, or discovered undocumented behavior that would help future agents — but only after calling zeabur-rag-search first to confirm the knowledge isn't already covered. Only contribute verified facts, not guesses or workarounds. The new chunk is marked unverified until an admin reviews it.
Interactive knowledge base curation loop — reviews pending items (reports, unverified chunks, failed queries, negative feedback) and walks through fixes one by one. Use when asked to "maintain the knowledge base", "review pending items", "run a curation round", "process reports", "clean up the KB", or any request to improve KB quality. This is the main entry point for the expand → organize → reflect cycle, and requires admin scope.
Send feedback on RAG search results — thumbs-up (+1) or thumbs-down (-1) to indicate whether the answer was helpful. Use after calling zeabur-rag-search when you can evaluate the quality of the results. Positive feedback reinforces good results; negative feedback flags poor matches for review. Requires write:feedback scope.
View a single chunk's full content plus related reports, search signals, and edit history. Use when you need to understand a chunk's context before editing, when investigating why a search result appeared, or when reviewing a reported issue. Triggers on "inspect chunk SUP-1234", "show chunk DOC-xxx", "chunk history", "why did this result appear", "look at this chunk". Requires admin scope.
List pending knowledge base maintenance items — open reports, unverified learned chunks, low-score queries, and negative feedback. Use when checking KB health, reviewing the maintenance queue, or starting a curation session. Triggers on "review queue", "what needs attention in the KB", "pending reports", "unverified chunks", "failed queries", "KB health check". Requires admin scope.
Edit the content of an existing chunk in the RAG knowledge base. Use when a chunk has a typo, outdated info, wrong tags, wrong visibility, or needs its title/question/answer rewritten — and you want the fix to take effect immediately. Requires admin scope. Prefer zeabur-rag-report for surfacing issues without write access.
