Query & Search

Show: All versions v2 only

The Query & Search API lets you ask a bucket a natural-language question and get back answer-ready context with source citations. Schift owns the full retrieval pipeline: embedding, hybrid retrieval, metadata filtering, reranking, context packing, and citation formatting.

Use this endpoint for user-facing retrieval, agent context assembly, and any integration that needs cited answers from bucket content.

API Versions

Version	Status	Notes
v2	Current	Consumer search with context and citations. Use for all new integrations.
v1	Deprecated	POST /v1/query, POST /v1/collections/\{name\}/search, and POST /v1/buckets/\{bucket_id\}/search. Kept for existing clients only.

Note: v1 search endpoints return Deprecation, Sunset, and Warning headers and a Link header pointing to the v2 successor.

POST /v2/buckets/{bucket_id}/search

Ask a bucket a question and return answer-ready context with citations.

Path parameters

Name	Type	Description
bucket_id	string	UUID or slug of the bucket to search.

Request body

Field	Type	Required	Default	Description
query	string	Yes	—	Natural-language question. Maximum 8,192 characters.
top_k	integer	No	8	Maximum number of cited passages to return.
context_budget	integer	No	2000	Approximate maximum context size in tokens.
filters	object	No	null	Metadata filters applied to candidate chunks.
options.rerank.enabled	boolean	No	true	Reorder candidate passages before context assembly.
options.rerank.top_k	integer	No	null	Number of candidate passages to rerank.
options.instructions.task	string	No	null	Search instruction preset: retrieval_query, retrieval_document, semantic_similarity, question_answering, clustering, classification, or code_retrieval.

Example request

curl -X POST ${API_BASE_URL:-https://api.schift.io}/v2/buckets/product-docs/search \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What changed in the enterprise plan?",
    "top_k": 8,
    "context_budget": 4000,
    "filters": {"status": "published"},
    "options": {
      "rerank": {"enabled": true, "top_k": 20},
      "instructions": {"task": "retrieval_query"}
    }
  }'

Response

Field	Type	Description
status	string	ready if the bucket returned context, otherwise empty.
operational_status	string	ready, empty, indexing, or degraded.
bucket_id	string	Bucket that was searched.
query	string	Question that was searched.
context	string	Answer-ready context assembled from bucket content, with numbered citations such as [1].
citations	array	Source references for the returned context.
citations[].index	integer	Citation number used in context.
citations[].document_id	string	Document that supports this passage.
citations[].source_id	string	Uploaded source or file ID, when available.
citations[].title	string	Human-readable source title.
citations[].source_url	string	Source URL, when available.
citations[].page	integer | string	Page or location in the source.
citations[].section	string	Section heading, when available.
warnings	array	Readiness, retrieval, or quality warnings.
warnings[].code	string	Stable machine-readable warning code.
warnings[].message	string	Human-readable warning message.
warnings[].severity	string	warning or error.

Index health reference

operational_status describes the bucket, not the query:

Value	Meaning	What to do
ready	The index matches the source.	Nothing.
empty	The bucket holds no searchable content yet.	Upload documents, or wait for the first ingest to finish.
indexing	Ingest is in flight, so coverage is still growing.	Retry later; results so far are valid but incomplete.
degraded	The index and the source disagree. Read warnings for which way.	Follow the repair value in warnings[].details.

warnings[].code is stable. The full set:

Code	Meaning	details.repair
INDEX_DRIFT_DETECTED	Fewer vectors than source chunks: some content is not searchable. No content is lost.	chunk_backfill_required
INDEX_SUPERSEDED_VECTORS	Older generations of chunks are indexed alongside the current ones. Nothing is missing; duplicates compete for ranking. Re-uploading does not clear them — it adds another generation.	generation_sweep_required
INDEX_ORPHAN_VECTORS	Vectors remain for source rows that no longer exist. Search can return content that is gone.	orphan_sweep_required

warnings[].details carries the measurements behind the code — sql_chunks (current logical chunks), sql_chunk_rows (all stored chunk rows including superseded generations), engine_vectors (live indexed vectors), and the counts named by the code. sql_chunk_rows minus sql_chunks is the superseded count; engine_vectors minus sql_chunk_rows is the orphan count. Comparing engine_vectors against sql_chunks alone overstates the problem, because the two are counted in different units.

Both sweeps are operator actions. Contact support with your bucket ID rather than re-uploading — a re-upload cannot clear either condition on its own.

Example response

{
  "status": "ready",
  "operational_status": "ready",
  "bucket_id": "product-docs",
  "query": "What changed in the enterprise plan?",
  "context": "[1] Enterprise seats now include advanced audit logging. [2] The monthly seat limit was removed for annual contracts.",
  "citations": [
    {
      "index": 1,
      "document_id": "doc_042",
      "source_id": "upload_123",
      "title": "Pricing Notes",
      "source_url": null,
      "page": 4,
      "section": "Enterprise",
      "score": 0.91
    },
    {
      "index": 2,
      "document_id": "doc_055",
      "source_id": "upload_124",
      "title": "Contract Terms",
      "source_url": null,
      "page": 2,
      "section": null,
      "score": 0.87
    }
  ],
  "warnings": []
}

Error examples

// 400 Bad Request — invalid filter
{
  "detail": "Invalid filter: unsupported operator"
}

// 400 Bad Request — unsupported knowledge-search filter key
{
  "error": "unsupported_knowledge_search_filter",
  "message": "Knowledge search filters must use validated user metadata or documented system filter keys.",
  "invalid_keys": ["internal_tag"]
}

// 402 Payment Required
{
  "allowed": false,
  "reason": "quota_exceeded"
}

// 403 Forbidden
{
  "detail": "Search quota unavailable. Upgrade your plan."
}

// 404 Not Found
{
  "detail": "Bucket 'product-docs' not found"
}

GET /v2/buckets/{bucket_id}/search/status

Check whether a bucket has searchable content before sending user traffic.

Path parameters

Name	Type	Description
bucket_id	string	UUID or slug of the bucket to check.

Example request

curl ${API_BASE_URL:-https://api.schift.io}/v2/buckets/product-docs/search/status \
  -H "Authorization: Bearer $SCHIFT_API_KEY"

Response

Field	Type	Description
status	string	ready if the bucket has searchable content, otherwise empty.
operational_status	string	ready, empty, indexing, or degraded.
bucket_id	string	Bucket that was checked.
indexed_count	integer | null	Number of searchable content items.
document_count	integer | null	Number of documents in this bucket.
pending_job_count	integer | null	Documents still being prepared.
failed_job_count	integer | null	Documents that need attention.
last_indexed_at	string | null	Most recent time content became searchable.
backfill_required	boolean	Whether existing documents need preparation.

Example response

{
  "status": "ready",
  "operational_status": "ready",
  "bucket_id": "product-docs",
  "indexed_count": 1240,
  "document_count": 42,
  "pending_job_count": 0,
  "failed_job_count": 0,
  "last_indexed_at": "2026-06-18T09:12:34Z",
  "backfill_required": false
}

Legacy v1 endpoints

The following endpoints are deprecated and should not be used in new integrations:

• POST /v1/query — use POST /v2/buckets/{bucket_id}/search instead.
• POST /v1/collections/\{name\}/search — use POST /v2/buckets/{bucket_id}/collections/{collection_id}/search instead.
• POST /v1/buckets/\{bucket_id\}/search — use POST /v2/buckets/{bucket_id}/search instead.

These routes expose lower-level retrieval mechanics. v2 intentionally hides that complexity behind the knowledge-search product API.

See also

• Buckets
• Filter Operators
• Response Shaping