응답 셰이핑

include_fields (화이트리스트)

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

각 결과에 나열된 필드만 반환. 점 표기 (metadata.X)로 metadata 하위 키 지정. Top-level 필드: id, score, text, metadata, neighbors, citation.

exclude_fields (블랙리스트)

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

나열된 필드를 제거. 모바일 클라이언트 payload 다이어트, 내부 metadata 노출 차단 등. 둘 다 설정되면 include_fields 우선.

citation_format

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

각 결과에 citation 문자열 부착. {key} 토큰은 metadata에서 치환. id/score/text는 top-level fallback. 알 수 없는 토큰은 빈 문자열로 렌더 (fail-soft).

결합 예시

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": "축구 오프사이드 룰",
    "top_k": 10,
    "citation_format": "[{title}:{page}]",
    "exclude_fields": ["text"]
  }'

캡

• include_fields / exclude_fields 각 64개 cap
• citation_format 최대 512자
• 알 수 없는 필드는 조용히 무시 (에러 아님)