クエリと検索

Show: All versions v2 only

クエリと検索APIを使用すると、バケットに自然言語の質問を投げかけ、引用付きの回答準備が整ったコンテキストを取得できます。Schiftは、埋め込み、ハイブリッド検索、メタデータフィルタリング、再ランキング、コンテキストパッキング、引用形式化の全ての検索パイプラインを所有しています。

このエンドポイントは、ユーザー向けの検索、エージェントコンテキストの組み立て、バケットコンテンツから引用付きの回答が必要な統合に使用します。

APIバージョン

Version	Status	Notes
v2	Current	contextとcitationsを使用した消費者検索。新しい統合にはこれを使用してください。
v1	Deprecated	POST /v1/query、POST /v1/collections/\{name\}/search、およびPOST /v1/buckets/\{bucket_id\}/search。既存のクライアントのみのために保持されています。

Note: v1の検索エンドポイントは、Deprecation、Sunset、Warningヘッダーと、v2の後継へのLinkヘッダーを返します。

POST /v2/buckets/{bucket_id}/search

バケットに質問を投げかけ、引用付きの回答準備が整ったコンテキストを返します。

Path parameters

Name	Type	Description
bucket_id	string	検索するバケットのUUIDまたはスラッグ。

Request body

Field	Type	Required	Default	Description
query	string	Yes	—	自然言語の質問。最大8,192文字。
top_k	integer	No	8	返す引用付きパッセージの最大数。
context_budget	integer	No	2000	トークンでのコンテキストサイズの概算最大値。
filters	object	No	null	候補チャンクに適用されるメタデータフィルター。
options.rerank.enabled	boolean	No	true	コンテキスト組み立て前に候補パッセージを再注文します。
options.rerank.top_k	integer	No	null	再ランキングする候補パッセージの数。
options.instructions.task	string	No	null	検索指示プリセット：retrieval_query、retrieval_document、semantic_similarity、question_answering、clustering、classification、または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、それ以外はempty。
operational_status	string	ready、empty、indexing、またはdegraded。
bucket_id	string	検索されたバケット。
query	string	検索された質問。
context	string	バケットコンテンツから組み立てられた回答準備が整ったコンテキスト。番号付きの引用（例：[1]）を含む。
citations	array	返されたコンテキストのソース参照。
citations[].index	integer	contextで使用される引用番号。
citations[].document_id	string	このパッセージをサポートするドキュメント。
citations[].source_id	string	アップロードされたソースまたはファイルID（利用可能な場合）。
citations[].title	string	人間が読めるソースタイトル。
citations[].source_url	string	ソースURL（利用可能な場合）。
citations[].page	integer | string	ソースのページまたは位置。
citations[].section	string	セクション見出し（利用可能な場合）。
warnings	array	準備、検索、または品質に関する警告。
warnings[].code	string	安定した機械可読の警告コード。
warnings[].message	string	人間が読める警告メッセージ。
warnings[].severity	string	warningまたは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

ユーザーのトラフィックを送信する前に、バケットに検索可能なコンテンツがあるかどうかを確認します。

Path parameters

Name	Type	Description
bucket_id	string	チェックするバケットのUUIDまたはスラッグ。

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、それ以外はempty。
operational_status	string	ready、empty、indexing、またはdegraded。
bucket_id	string	チェックされたバケット。
indexed_count	integer | null	検索可能なコンテンツアイテムの数。
document_count	integer | null	このバケット内のドキュメントの数。
pending_job_count	integer | null	まだ準備中のドキュメント。
failed_job_count	integer | null	注意が必要なドキュメント。
last_indexed_at	string | null	コンテンツが検索可能になった最新の時間。
backfill_required	boolean	既存のドキュメントが準備を必要とするかどうか。

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
}

レガシーv1エンドポイント

以下のエンドポイントは非推奨であり、新しい統合では使用しないでください：

• POST /v1/query — 代わりにPOST /v2/buckets/{bucket_id}/searchを使用してください。
• POST /v1/collections/\{name\}/search — 代わりにPOST /v2/buckets/{bucket_id}/collections/{collection_id}/searchを使用してください。
• POST /v1/buckets/\{bucket_id\}/search — 代わりにPOST /v2/buckets/{bucket_id}/searchを使用してください。

これらのルートは低レベルの検索メカニズムを公開しています。v2は意図的にその複雑さを知識検索製品APIの背後に隠しています。

See also

• バケット
• Filter Operators
• Response Shaping