Search is a POST on each knowledge base: you send a query string plus optional limit / nextCursor and settings (e.g. searchMode semantic or hybrid, retrieveTopK, rerank (enabled/disabled) + optional rerank.topK, includeSourceMetadata). The format query parameter (the only allowed query key) selects how each hit’s content is projected. Responses are JSON with hits and optional nextCursor (see the spec for hybrid/rerank pagination rules). See the search endpoint in the API reference for exact request and response schemas; use API Runner to experiment with format and settings before codifying them.
Tip: the snippets are meant to be copy/paste friendly—start with the happy path, then intentionally poke at scopes, missing fields, and bad inputs so you know exactly what your app will see in production.
- Request shape
formatprojects hit text (markdown,html,text,json,doctags).includeSourceMetadatafor citations and source context.nextCursorfor stable pagination.
- Defaults & experiments
- Prefer hybrid when the corpus has exact tokens (SKUs, error codes, API paths).
- Keep retrieval defaults in KB config so tuning does not require redeploys.
- Benchmark retrieval profiles against evaluation datasets when you change settings or providers.
- For supported embedding models, rerank providers, and KB configuration fields, read Embedding models & rerank providers.
KB search (search:run; only ?format=… as query key; body is SearchRequest JSON)
curl -s -X POST "https://api.indexify.dev/projects/550e8400-e29b-41d4-a716-446655440001/kbs/660e8400-e29b-41d4-a716-446655440002/search?format=markdown" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtYWNoaW5lIn0.dBjftJeZ4CVP-mB92K27uhbUJU1p1b_wW1gFWFOEjXk" \
-H "Content-Type: application/json" \
-d '{"query":"refund policy","limit":8,"settings":{"searchMode":"hybrid","retrieveTopK":50,"rerank":{"isEnabled":"no"},"includeSourceMetadata":true,"includeGrounding":false,"diagnostics":false,"groupBy":null}}'Widen the first-stage candidate set (retrieveTopK, hybrid mode), then optionally rerank to fit the best passages in your model context (rerank.topK). Request fields live on POST …/search and in KB defaults—full schema in API reference. Provider configuration: Embedding models & rerank. The cURL example opens api-docs and API Runner.
If you’re reading this as a reference, feel free to jump around—each section is written to stand on its own, and the left-hand search is the fastest way to find a specific endpoint or concept.
Retrieve a broad candidate set (semantic + lexical when using hybrid), then rerank so only the strongest passages reach your model. The cURL sample targets POST …/search. Provider ids: Rerank providers.
Tip: the snippets are meant to be copy/paste friendly—start with the happy path, then intentionally poke at scopes, missing fields, and bad inputs so you know exactly what your app will see in production.
- Two-stage flow
- Rerank to fit high-signal passages in the LLM budget.
- Return citations from the final ranked list.
Retrieval profile for production Q&A Rerank provider and model are configured on the knowledge base (not in this request); the body only enables rerank and sets sizes.
curl -s -X POST "https://api.indexify.dev/projects/550e8400-e29b-41d4-a716-446655440001/kbs/660e8400-e29b-41d4-a716-446655440002/search?format=markdown" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtYWNoaW5lIn0.dBjftJeZ4CVP-mB92K27uhbUJU1p1b_wW1gFWFOEjXk" \
-H "Content-Type: application/json" \
-d '{
"query": "how do I rotate API credentials safely?",
"settings": {
"searchMode": "hybrid",
"retrieveTopK": 50,
"rerank": { "isEnabled": "yes", "topK": 8 },
"includeSourceMetadata": true
}
}'Treat retrieval tuning as an offline measurement loop: labeled questions, expected sources, and regression checks whenever you change KB settings or providers (Glossary — integration quality).
Use the bullets as a checklist: read once, then keep this open while you implement so you don’t miss the small but important details (like token type, scopes, and strict query rules).
- Tuning knobs
retrieveTopK— how many candidates the first stage returns before rerank (trade recall vs cost).rerank.topK— how many chunks you pass to the model after reranking (trade precision vs context window).
Set settings.diagnostics: true on POST …/search to attach SearchDiagnostics (candidate counts, rerank path, timings, effective multimodal modes—no query echo). Use for eval loops and debugging; schema is on that route in API reference. MCP: diagnostics: true on indexify_search.
Tip: the snippets are meant to be copy/paste friendly—start with the happy path, then intentionally poke at scopes, missing fields, and bad inputs so you know exactly what your app will see in production.
- When to enable
- Development / eval — compare candidate pool sizes when you change hybrid, rerank, or filters.
- Agent refinement — if results are empty or noisy, diagnostics explain whether the pipeline saw zero merges, rerank, etc.
- Production — omit or set
falseby default to keep payloads small unless you sample a fraction of traffic.
Optional retrieval diagnostics (evaluate → refine, eval dashboards) diagnostics adds SearchDiagnostics: candidate counts, rerank path, durationMs — never echoes the query text.
curl -s -X POST "https://api.indexify.dev/projects/550e8400-e29b-41d4-a716-446655440001/kbs/660e8400-e29b-41d4-a716-446655440002/search?format=markdown" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJtYWNoaW5lIn0.dBjftJeZ4CVP-mB92K27uhbUJU1p1b_wW1gFWFOEjXk" \
-H "Content-Type: application/json" \
-d '{
"query": "password rotation policy",
"limit": 8,
"settings": {
"diagnostics": true,
"includeSourceMetadata": true,
"searchMode": "hybrid",
"retrieveTopK": 40,
"rerank": { "isEnabled": "yes", "topK": 8 }
}
}'