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.

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