Buckets

Show: All versions v2 only

**バケット（bucket）**は、Schiftの公開ナレッジ保存領域です。バケットを使用すると、ドキュメントをアップロードし、インデックスの準備状況を確認し、引用付きの回答用コンテキストを検索し、ナレッジベースに属するドキュメントを管理できます。

注： すべてのバケットエンドポイントには、Authorization: Bearer <SCHIFT_API_KEY>ヘッダーが必要です。バケットやドキュメントを作成・変更・削除するエンドポイントには、buckets:manageスコープが必要です。読み取りおよび検索エンドポイントは、組織の制限内で有効なAPIキーを受け入れます。

API Versions

公開製品APIはv2です。新規統合では、以下に記載されている/v2/buckets/*ルートを使用してください。

古い/v1/buckets/*ルートは、既存のクライアント向けの非推奨互換性サーフェスです。引き続き動作しますが、v1検索エンドポイントはDeprecationおよびLinkの後続バージョンヘッダーを返し、v2の相当するエンドポイントを示します。パブリックバケットは、両方のバージョンで読み取り専用です。

Bucket object

Field	Type	Description
id	string	一意のバケット識別子。
name	string	人間が読めるバケット名。
description	string	オプションの説明。
dimension	integer	バケットに設定された埋め込み次元。
model	string	バケットに使用される埋め込みモデル。
backend	string	ベクトルバックエンド。例：engine。
file_count	integer	アップロードされたドキュメント数。
vector_count	integer	インデックスされたベクトル数。
active_job_count	integer	このバケットの進行中のジョブ数。
created_at	string	ISO 8601作成タイムスタンプ。
default_privacy_level	integer	バケットコンテンツのデフォルトプライバシーレベル。
max_privacy_level	integer	許可される最大プライバシーレベル。
external_max_privacy_level	integer	外部に公開される最大プライバシーレベル。
enforce_access_policy	boolean	アクセスポリシーが強制されるかどうか。
scope_by_department	boolean	部署メタデータによってアクセスが制限されるかどうか。

POST /v2/buckets

新しいバケットを作成します。Schiftは、埋め込みモデル、次元、バックエンドを自動的に構成します。

Request body

Field	Type	Required	Default	Description
name	string	Yes	—	バケット名。__schift_で始まってはいけません。
description	string	No	""	オプションの説明。
metadata	object	No	null	自由形式のユーザーメタデータ。
default_privacy_level	integer	No	3	デフォルトのプライバシーレベル。
max_privacy_level	integer	No	10	最大プライバシーレベル。
external_max_privacy_level	integer	No	1	外部プライバシー上限。
enforce_access_policy	boolean	No	true	アクセスポリシーの強制を有効にします。
scope_by_department	boolean	No	false	部署別のアクセス範囲を適用します。

Request example

{
  "name": "product-docs",
  "description": "Product support knowledge"
}

Response example

{
  "id": "bucket_01J8X1234567890ABCDEF",
  "name": "product-docs",
  "description": "Product support knowledge",
  "dimension": 1024,
  "model": "text-embedding-3-large",
  "backend": "engine",
  "file_count": 0,
  "vector_count": 0,
  "active_job_count": 0,
  "created_at": "2026-06-19T05:00:00Z",
  "default_privacy_level": 3,
  "max_privacy_level": 10,
  "external_max_privacy_level": 1,
  "enforce_access_policy": false,
  "scope_by_department": false
}

Errors

Status	Cause
400	無効なリクエストボディ。
403	バケット名が予約された__schift_名前空間を使用しています。
409	同じ名前のバケットが既に存在します。

GET /v2/buckets

認証された組織のバケットを一覧表示します。

Response example

[
  {
    "id": "bucket_01J8X1234567890ABCDEF",
    "name": "product-docs",
    "description": "Product support knowledge",
    "dimension": 1024,
    "model": "text-embedding-3-large",
    "backend": "engine",
    "file_count": 12,
    "vector_count": 128,
    "active_job_count": 0,
    "created_at": "2026-06-19T05:00:00Z",
    "default_privacy_level": 3,
    "max_privacy_level": 10,
    "external_max_privacy_level": 1,
    "enforce_access_policy": false,
    "scope_by_department": false
  }
]

GET /v2/buckets/{bucket_id}

IDで単一のバケットを取得します。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。

Response example

POST /v2/bucketsの応答と同じ形式です。

Errors

Status	Cause
404	バケットが見つからないか、アクセスできません。

PATCH /v2/buckets/{bucket_id}

変更可能なバケットフィールドを変更します。現在、名前の変更、説明の更新、およびプライバシーポリシーフィールドを含むメタデータの更新をサポートしています。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。

Request body

すべてのフィールドはオプションです。

Field	Type	Description
name	string	新しいバケット名。
description	string	新しい説明。
metadata	object	既存のメタデータにマージされる自由形式のメタデータ。
default_privacy_level	integer	デフォルトのプライバシーレベル。
max_privacy_level	integer	最大プライバシーレベル。
external_max_privacy_level	integer	外部プライバシー上限。
enforce_access_policy	boolean	アクセスポリシーの強制を有効にします。
scope_by_department	boolean	部署別のアクセス範囲を適用します。

Request example

{
  "description": "Updated product support knowledge"
}

Response example

POST /v2/bucketsの応答と同じ形式です。

Errors

Status	Cause
403	パブリックバケットは読み取り専用です。
404	バケットが見つかりません。
409	新しいバケット名は既に使用されています。

DELETE /v2/buckets/{bucket_id}

バケットの削除をキューに入れます。削除は非同期に実行され、ジョブIDを返します。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。

Response example

{
  "bucket_id": "bucket_01J8X1234567890ABCDEF",
  "job_id": "job_01J8Y1234567890ABCDEF",
  "status": "queued",
  "delete_requested_at": "2026-06-19T05:05:00Z"
}

Errors

Status	Cause
403	パブリックバケットは読み取り専用です。
404	バケットが見つかりません。

GET /v2/buckets/{bucket_id}/collections

バケット内の子コレクションを一覧表示します。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。

Response example

[
  {
    "id": "col_01J8X1234567890ABCDEF",
    "bucket_id": "bucket_01J8X1234567890ABCDEF",
    "name": "migration-guides",
    "description": "",
    "dimension": 1024,
    "model": "text-embedding-3-large",
    "backend": "engine",
    "file_count": 4,
    "vector_count": 42,
    "active_job_count": 0
  }
]

Errors

Status	Cause
404	バケットが見つかりません。

GET /v2/buckets/{bucket_id}/search/status

バケットが質問に回答できる準備ができているかどうかを確認します。このエンドポイントは、検索を実行せずに、消費者向けの準備状況サマリーを返します。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。

Response example

{
  "status": "ready",
  "operational_status": "ready",
  "bucket_id": "product-docs",
  "indexed_count": 128,
  "document_count": 12,
  "pending_job_count": 0,
  "failed_job_count": 0,
  "last_indexed_at": "2026-06-19T04:55:00Z",
  "backfill_required": false
}

Errors

Status	Cause
404	バケットが見つかりません。

POST /v2/buckets/{bucket_id}/search

管理されたナレッジ検索パイプラインを実行し、引用付きの回答用コンテキストを返します。呼び出し元は、埋め込みルート、ベクトルモード、またはリランク機構を選択する必要はありません。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。

Request body

Field	Type	Required	Default	Description
query	string	Yes	—	バケットに対して尋ねる質問。
top_k	integer	No	8	返す最大引用パッセージ数。範囲は1–100。
context_budget	integer	No	2000	おおよその最大コンテキストサイズ（トークン数）。範囲は100–32000。
filters	object	No	null	メタデータフィルタ。詳細はFiltersを参照。
options.rerank.enabled	boolean	No	true	コンテキスト組み立て前に引用の順序を改善します。
options.rerank.top_k	integer	No	null	リランクする候補パッセージ数。範囲は1–1000。
options.instructions.task	string	No	null	retrieval_queryなどの検索指示プリセット。

Request example

{
  "query": "How do I migrate embedding models?",
  "top_k": 8,
  "context_budget": 4000,
  "filters": {"product": "schift"},
  "options": {
    "rerank": {"enabled": true, "top_k": 20},
    "instructions": {"task": "retrieval_query"}
  }
}

Response example

{
  "status": "ready",
  "operational_status": "ready",
  "bucket_id": "product-docs",
  "query": "How do I migrate embedding models?",
  "context": "[1] Migration guide excerpt...",
  "citations": [
    {
      "index": 1,
      "document_id": "doc_042",
      "source_id": "doc_042",
      "title": "Migration Guide",
      "source_url": null,
      "page": null,
      "section": null
    }
  ],
  "warnings": []
}

Errors

Status	Cause
400	無効なフィルタまたはリクエストボディ。
402	検索クォータを超過しました。
403	検索クォータが利用できないか、プランの制限です。
404	バケットが見つかりません。

POST /v2/buckets/{bucket_id}/collections/{collection_id}/search

生のv2検索コントラクトを使用して、バケット内の単一のコレクションを検索します。これは、バケット全体ではなく特定の子コレクションから結果を取得したい場合に便利です。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。
collection_id	string	Yes	コレクション識別子。

Request body

Field	Type	Required	Default	Description
query	string	Yes*	""	テキストクエリ。queryまたはqueryVectorのいずれかが必要です。
queryVector	number[]	Yes*	null	生の埋め込みベクトル。
topK	integer	No	10	最大結果数。範囲は1–1000。
model	string	No	null	埋め込みモデルのオーバーライド。
filter	object	No	null	メタデータフィルタ。
accessMode	string	No	auto	auto、internal、externalのいずれか。rawは内部専用です。
mode	string	No	hybrid	vectorまたはhybrid。
rerank	boolean	No	false	リランクを有効にします。
rerankTopK	integer	No	null	リランク用の候補数。
minScore	number	No	null	最小結果スコア。範囲は0–1。
debug	boolean	No	false	デバッグタイミングとスコアを含めます。

Response example

{
  "bucket_id": "product-docs",
  "query": "migration",
  "search_id": "search_01J8X1234567890ABCDEF",
  "results": [
    {
      "id": "chunk_042",
      "score": 0.923,
      "text": "Migration guide excerpt...",
      "metadata": {"document_id": "doc_042"},
      "citation": null
    }
  ],
  "degraded": false,
  "warnings": []
}

Errors

Status	Cause
400	queryまたはqueryVectorが欠落しているか、無効な時系列パラメータです。
403	raw取得モードは内部専用です。
404	バケットまたはコレクションが見つかりません。

POST /v2/buckets/{bucket_id}/documents

1つ以上のファイルをバケットにアップロードします。アップロードされたファイルは、非同期に抽出、チャンク化、埋め込み、インデックス化されます。このエンドポイントはmultipart/form-dataを受け入れます。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。

Form fields

Field	Type	Required	Default	Description
files	file	Yes	—	1つ以上のファイル。PDF、Markdown、テキスト、Officeドキュメント、画像がサポートされています。
ocr_strategy	string	No	auto	画像ベースのドキュメントに対するOCR戦略。
chunk_size	integer	No	512	目標チャンクサイズ。範囲は64–8192。
chunk_overlap	integer	No	50	チャンクのオーバーラップ。範囲は0–512。
metadata	string	No	null	アップロードされた各ファイルに添付されるJSON文字列化されたオブジェクト。
collection_id	string	No	null	対象の子コレクション。デフォルトはバケットです。

Request example

curl -X POST ${API_BASE_URL}/v2/buckets/product-docs/documents \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "ocr_strategy=auto" \
  -F "chunk_size=512" \
  -F 'metadata={"source":"support","product":"schift"}'

Response example

{
  "jobs": [
    {
      "job_id": "job_01J8X1234567890ABCDEF",
      "document_id": "doc_01J8X1234567890ABCDEF",
      "file_name": "manual.pdf",
      "file_type": "pdf",
      "status": "queued",
      "estimated_cost": 0.05
    }
  ],
  "total_estimated_cost": 0.05
}

Errors

Status	Cause
400	サポートされていないファイルタイプまたは無効なフォームデータ。
403	APIキーにbuckets:manageスコープがありません。
404	バケットが見つかりません。
413	ファイルまたはリクエストがアップロード制限を超えています。

GET /v2/buckets/{bucket_id}/documents

バケット内のドキュメントを一覧表示します。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。

Query parameters

Parameter	Type	Required	Default	Description
status	string	No	—	ドキュメントのステータスでフィルタリング。
limit	integer	No	50	最大結果数。範囲は1–500。

Response example

[
  {
    "id": "doc_01J8X1234567890ABCDEF",
    "bucket_id": "product-docs",
    "collection_id": null,
    "file_name": "manual.pdf",
    "file_type": "pdf",
    "status": "ready",
    "metadata": {"source": "support", "product": "schift"},
    "source_metadata": {},
    "latest_job_id": "job_01J8X1234567890ABCDEF",
    "latest_successful_job_id": "job_01J8X1234567890ABCDEF",
    "last_error_summary": null,
    "created_at": "2026-06-19T04:00:00Z",
    "updated_at": "2026-06-19T04:05:00Z"
  }
]

Errors

Status	Cause
404	バケットが見つかりません。

GET /v2/buckets/{bucket_id}/documents/{document_id}

IDで単一のドキュメントを取得します。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。
document_id	string	Yes	ドキュメント識別子。

Response example

GET /v2/buckets/{bucket_id}/documents応答の単一アイテムと同じ形式です。

Errors

Status	Cause
404	バケットまたはドキュメントが見つかりません。

PATCH /v2/buckets/{bucket_id}/documents/{document_id}

ドキュメントのメタデータを更新します。検索の可視性に影響する変更は、デフォルトで再インデックスをトリガーします。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。
document_id	string	Yes	ドキュメント識別子。

Request body

Field	Type	Required	Default	Description
metadata	object	No	{}	マージするメタデータ。
public_accessible	boolean	No	null	ドキュメントが公開されているかどうか。
privacy_level	integer	No	null	プライバシーレベル。範囲は1–10。
classification	string	No	null	internal、public、restricted、confidentialのいずれか。
review_status	string	No	null	pending、approved、rejectedのいずれか。
reindex	boolean	No	true	更新後の再インデックスをキューに入れます。

Response example

GET /v2/buckets/{bucket_id}/documents/{document_id}応答と同じ形式です。

Errors

Status	Cause
400	無効なメタデータ。
404	バケットまたはドキュメントが見つかりません。

DELETE /v2/buckets/{bucket_id}/documents/{document_id}

ドキュメントの完全削除をキューに入れます。削除は非同期に実行され、ジョブIDを返します。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。
document_id	string	Yes	ドキュメント識別子。

Response example

{
  "bucket_id": "product-docs",
  "document_id": "doc_01J8X1234567890ABCDEF",
  "job_id": "job_01J8Y1234567890ABCDEF",
  "status": "queued",
  "delete_requested_at": "2026-06-19T05:10:00Z"
}

Errors

Status	Cause
404	バケットまたはドキュメントが見つかりません。

GET /v2/buckets/{bucket_id}/metadata-keys

バケット内のドキュメント全体にわたって表示されるメタデータキーと、それらの最も一般的な値を一覧表示します。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。

Query parameters

Parameter	Type	Required	Default	Description
limit	integer	No	500	キー用にスキャンする最大ドキュメント数。範囲は1–2000。
values_per_key	integer	No	20	キーあたりに返される最大値数。範囲は0–100。

Response example

{
  "bucket_id": "product-docs",
  "keys": [
    {
      "key": "product",
      "document_count": 12,
      "values": [
        {"value": "schift", "count": 10},
        {"value": "docs", "count": 2}
      ]
    }
  ]
}

Errors

Status	Cause
404	バケットが見つかりません。

GET /v2/buckets/{bucket_id}/metadata-keys/{key}/values

特定のメタデータキーで観察された値を一覧表示します。

Path parameters

Parameter	Type	Required	Description
bucket_id	string	Yes	バケット識別子。
key	string	Yes	メタデータキー。

Query parameters

Parameter	Type	Required	Default	Description
limit	integer	No	100	最大の異なる値数。範囲は1–1000。
document_limit	integer	No	2000	スキャンする最大ドキュメント数。範囲は1–10000。

Response example

{
  "bucket_id": "product-docs",
  "key": "product",
  "values": [
    {"value": "schift", "count": 10},
    {"value": "docs", "count": 2}
  ]
}

Errors

Status	Cause
404	バケットが見つからないか、メタデータキーが見つかりません。

関連項目

• バケットの概念
• Jobs
• Filters
• Response shaping