Docs

Knowledge Search

Search a bucket through the v2 pipeline and receive answer-ready context with citations.

Endpoint

bashPOST /v2/buckets/{bucket_id}/search

Use this endpoint for new search integrations. Clients provide the question, metadata filters, and optional rerank or instruction settings; Schift handles embedding, hybrid retrieval, reranking, context packing, and citation shaping on the server.

ParameterTypeDefaultDescription
querystring--Natural-language question or search query
top_kinteger8Candidate count before context packing
context_budgetinteger--Maximum context budget returned to the caller
filtersobject--Metadata filters from uploaded documents
options.rerank.enabledbooleanfalseEnable server-side reranking
options.rerank.top_kintegertop_kCandidate count retained after reranking
options.instructions.taskstring--Task hint for result shaping and context selection

Example

bashcurl -X POST https://api.schift.io/v2/buckets/{bucket_id}/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "How do I migrate embedding models?",
    "filters": {"doc_type": "guide"},
    "top_k": 8,
    "context_budget": 12000,
    "options": {
      "rerank": {"enabled": true, "top_k": 5},
      "instructions": {"task": "answer with concise cited evidence"}
    }
  }'