Docs

Query & Search

Search collections using natural language, pre-computed vectors, hybrid mode, reranking, and temporal constraints.

Vector Search

bashPOST /v1/query

Embed a query, project it into the collection's vector space, and return the most similar results. Supports text queries, pre-computed vectors, hybrid search, cross-encoder reranking, and temporal filtering.

Parameter	Type	Required	Default	Description
`query`	string	No*	--	Natural language query text
`query_vector`	float[]	No*	--	Pre-computed embedding (skips embed step)
`collection`	string	Yes	--	Collection name to search
`model`	string	No	Org config	Embedding model to use
`top_k`	integer	No	10	Number of results to return
`mode`	string	No	vector	`vector` or `hybrid` (vector + BM25 via RRF)
`rerank`	boolean	No	false	Enable cross-encoder reranking
`rerank_top_k`	integer	No	top_k	Results to keep after reranking
`rerank_model`	string	No	--	Reranker model override
`temporal`	string	No	--	`before`, `after`, `between`, `as_of`, or `latest`
`temporal_start`	integer	No	--	Epoch millis (required when temporal is set, except latest)
`temporal_end`	integer	No	--	Epoch millis (required for between)

Note

One of query or query_vector is required. Hybrid mode and reranking require a text query.

Basic Search

bashcurl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "How do I migrate embedding models?",
    "collection": "product-docs",
    "top_k": 5
  }'

Pre-computed Vector

Skip the embedding step by passing a pre-computed vector directly. The vector is still projected to match the collection dimension.

bashcurl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query_vector": [0.1, 0.2, ...],
    "collection": "product-docs",
    "top_k": 5
  }'

Hybrid Search

Combine vector similarity with BM25 keyword matching using Reciprocal Rank Fusion. Over-fetches 3x candidates before merging.

bashcurl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "employment contract termination clause",
    "collection": "legal-docs",
    "mode": "hybrid",
    "top_k": 10
  }'

Reranking

Re-score results with a cross-encoder model for higher precision. Results include both the original score and rerank_score.

bashcurl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "data retention policy",
    "collection": "compliance",
    "rerank": true,
    "rerank_top_k": 3
  }'

Temporal Search

Filter results by event_time metadata. Vectors without event_time are excluded from temporal queries.

bash# Documents from the last 7 days
curl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "recent policy changes",
    "collection": "policies",
    "temporal": "after",
    "temporal_start": 1711324800000
  }'

# Documents in a date range
curl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "quarterly report",
    "collection": "finance",
    "temporal": "between",
    "temporal_start": 1704067200000,
    "temporal_end": 1711929600000
  }'

Cross-Model Search

All vectors pass through Schift's canonical projection layer. You can store documents with one embedding model and query with another -- Schift handles the projection automatically.

bash# Documents were stored using OpenAI
# Query using a different model
curl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "embedding model migration",
    "collection": "product-docs",
    "model": "voyage/voyage-4-large",
    "top_k": 3
  }'