Response Shaping

include_fields (whitelist)

json{
  "query": "...",
  "include_fields": ["id", "score", "metadata.title", "metadata.page"]
}

Each result returns only the listed fields. Dotted paths like metadata.X scope into metadata sub-keys. Top-level fields: id, score, text, metadata, neighbors, citation.

exclude_fields (blacklist)

json{
  "query": "...",
  "exclude_fields": ["text", "metadata.internal_notes"]
}

Drops the listed fields. Useful for stripping large text payloads on bandwidth-constrained clients, or hiding internal-only metadata. include_fields takes precedence when both are set.

citation_format

json{
  "query": "...",
  "citation_format": "[{title}:{page}]"
}

Returns a citation string per result with {key} tokens substituted from metadata. Top-level fields (id, score, text) are also accessible. Unknown tokens render empty (fail-soft).

Combined

bashcurl -X POST https://api.schift.io/v1/buckets/{bucket_id}/search \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "soccer offside rule",
    "top_k": 10,
    "citation_format": "[{title}:{page}]",
    "exclude_fields": ["text"]
  }'

Caps

• include_fields / exclude_fields capped at 64 entries each
• citation_format max 512 chars
• Unknown fields are silently ignored (no error)