> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ナレッジ API
> ナレッジベース、ドキュメント、チャンク、メタデータ、タグ、ナレッジパイプラインを扱う API
Dify コンソールを介さず、自分のコードから [ナレッジベース](/ja/3.13.x/use/knowledge/readme) を構築・管理できます。ナレッジベースを作成し、ドキュメントとチャンクを取り込み、メタデータとタグで整理し、検索や RAG のために直接クエリできます。
## API エンドポイントとキーの取得
**ナレッジ** 画面右上の **サービスAPI** をクリックすると、API 設定パネルが開きます。ここから以下を行えます。
* サービスAPI エンドポイントをコピーします。すべてのナレッジ API リクエストのベース URL です。
* **APIキー** をクリックしてキーを作成・管理します。
API キーのスコープを限定する
連携先で一部のナレッジベースだけを扱う場合は、キーの作成時にそのナレッジベースを選びます。ナレッジベースの一覧取得や作成が必要な場合は、すべてのナレッジベースを選んでください。
スコープを限定したキーで呼び出せるのは、パスにスコープ内の `dataset_id` を含むエンドポイントだけです。別の ID を指定した場合や、パスに `dataset_id` がない場合は、403 `forbidden` が返ります。
スコープを限定したキーで使う ID は、Dify で対象のナレッジベースを開いて取得します。ページ URL の `/datasets/` の後にある ID をコピーし、リクエストパスの `dataset_id` に指定してください。
スコープを変更するには、新しいキーを作成します。連携先を新しいキーに切り替えてから、古いキーを削除してください。
ナレッジベースを削除すると、そのナレッジベースだけに限定されたキーも削除されます。他のナレッジベースも対象に含むキーは、それらに対して引き続き使えます。
API キーはサーバー側で安全に保管してください。クライアントコードや公開リポジトリには絶対に含めないでください。
## ナレッジベースの API アクセス管理
既定では、すべてのナレッジベースで API アクセスが有効です。特定のナレッジベースへの API アクセスをすべてのキーで無効にするには、対象のナレッジベースを開き、左下の **API アクセス** をオフにします。
## ナレッジベースの作成と管理
* **[空のナレッジベースを作成](/ja/3.13.x/develop/api/knowledge-bases/create-an-empty-knowledge-base)**：ドキュメントを含まないナレッジベースを作成します。
* **[ナレッジベースリストを取得](/ja/3.13.x/develop/api/knowledge-bases/list-knowledge-bases)**：キーワードやタグで絞り込めるページネーション付きリストを返します。
* **[ナレッジベース詳細を取得](/ja/3.13.x/develop/api/knowledge-bases/get-knowledge-base)**：埋め込みモデル、検索設定、ドキュメント統計を返します。
* **[ナレッジベースを更新](/ja/3.13.x/develop/api/knowledge-bases/update-knowledge-base)**：名前、権限、埋め込みモデル、検索設定を変更します。リクエストで指定したフィールドのみを更新します。
* **[ナレッジベースを削除](/ja/3.13.x/develop/api/knowledge-bases/delete-knowledge-base)**：ナレッジベースとその中のすべてのドキュメント、そしてそのナレッジベースだけに限定された API キーを完全に削除します。
* **[ナレッジベースからチャンクを取得 / テスト検索](/ja/3.13.x/develop/api/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval)**：ナレッジベースを検索し、最も関連性の高いチャンクを返します。本番検索と検索テストの両方に同じエンドポイントを使います。
## ドキュメントの追加と更新
ドキュメントの作成は非同期です。作成後、インデックスが完了するまでポーリングします。
[空のナレッジベースを作成](/ja/3.13.x/develop/api/knowledge-bases/create-an-empty-knowledge-base) を呼び出します。既存のナレッジベースをそのまま使うこともできます。
[テキストからドキュメントを作成](/ja/3.13.x/develop/api/documents/create-document-by-text) または [ファイルからドキュメントを作成](/ja/3.13.x/develop/api/documents/create-document-by-file) を呼び出します。どちらも `batch` ID を返します。
ナレッジベース作成時に `indexing_technique`（検索用に内容をインデックスする方法）を設定しなかった場合は、この最初のドキュメントで設定します。以降のドキュメントには自動的に引き継がれます。
`batch` ID を使って [ドキュメント埋め込みステータス（進捗）を取得](/ja/3.13.x/develop/api/documents/get-document-indexing-status) をポーリングします。`indexing_status` が `completed` または `error` になるまで待ちます。処理は `waiting`、`parsing`、`cleaning`、`splitting`、`indexing` の順に進みます。
* **[ナレッジベースのドキュメントリストを取得](/ja/3.13.x/develop/api/documents/list-documents)**：キーワードやインデックスステータスで絞り込めるページネーション付きリストを返します。
* **[ドキュメント詳細を取得](/ja/3.13.x/develop/api/documents/get-document)**：インデックスステータス、メタデータ、処理統計を返します。`metadata` クエリパラメータで、メタデータフィールドを含める・省略する・のみ返すのいずれかを指定できます。
* **[ドキュメントをダウンロード](/ja/3.13.x/develop/api/documents/download-document)**：ドキュメントの元ファイルに対する署名付きダウンロード URL を返します。
* **[ドキュメントを一括ダウンロード（ZIP）](/ja/3.13.x/develop/api/documents/download-documents-as-zip)**：ファイルからアップロードしたドキュメントを最大 100 件、1 つのアーカイブにまとめます。
* **[ドキュメントを更新](/ja/3.13.x/develop/api/documents/update-document)**：新しいファイルをアップロードして内容を置き換え、インデックスを再実行します。これがファイルベースのドキュメントを更新する標準的な方法です。
* **[テキストでドキュメントを更新](/ja/3.13.x/develop/api/documents/update-document-by-text)**：ドキュメントのテキスト内容、名前、処理設定をインラインで更新します。内容が変わるとインデックスを再実行します。
* **[ファイルでドキュメントを更新](/ja/3.13.x/develop/api/documents/update-document-by-file)**：置き換え用のファイルをアップロードするための非推奨のエイリアスです。代わりに「ドキュメントを更新」を使用してください。
* **[ドキュメントステータスを一括更新](/ja/3.13.x/develop/api/documents/update-document-status-in-batch)**：複数のドキュメントを一度に有効化・無効化・アーカイブ・アーカイブ解除します。
* **[ドキュメントを削除](/ja/3.13.x/develop/api/documents/delete-document)**：ドキュメントとその中のすべてのチャンクを完全に削除します。
## チャンクと子チャンクの管理
* **[ドキュメントにチャンクを追加](/ja/3.13.x/develop/api/chunks/create-chunks)**：チャンクを手動でドキュメントに追加します（アップロードされた内容は、インデックス処理が自動でチャンク化します）。各チャンクには `content` が必須で、Q\&A モードのドキュメントでは `answer` も必須です。
* **[チャンク一覧を取得](/ja/3.13.x/develop/api/chunks/list-chunks)**：キーワードやステータスで絞り込めるページネーション付きリストを返します。
* **[ドキュメント内のチャンク詳細を取得](/ja/3.13.x/develop/api/chunks/get-chunk)**：チャンクの内容、キーワード、インデックスステータスを返します。
* **[ドキュメント内のチャンクを更新](/ja/3.13.x/develop/api/chunks/update-chunk)**：チャンクの内容、キーワード、回答を変更し、そのチャンクのインデックスを再実行します。
* **[ドキュメント内のチャンクを削除](/ja/3.13.x/develop/api/chunks/delete-chunk)**：チャンクを完全に削除します。
親子モード（`hierarchical_model`）のドキュメントでは、子チャンクは親チャンクの配下に置かれます。API から作成・更新した子チャンクは常に `customized` になり、インデックス処理が自動生成する `automatic` とは区別されます。
* **[子チャンクを作成](/ja/3.13.x/develop/api/chunks/create-child-chunk)**：親チャンクの下に子チャンクを追加します。
* **[子チャンク一覧を取得](/ja/3.13.x/develop/api/chunks/list-child-chunks)**：親チャンク配下の子チャンクをページネーション付きで返します。
* **[子チャンクを更新](/ja/3.13.x/develop/api/chunks/update-child-chunk)**：子チャンクの内容を変更します。
* **[子チャンクを削除](/ja/3.13.x/develop/api/chunks/delete-child-chunk)**：子チャンクを完全に削除します。
## メタデータフィールドの管理
メタデータフィールドはドキュメントに構造化情報を付与し、検索時のフィルタリングに使えます。
* **[メタデータフィールドを作成](/ja/3.13.x/develop/api/metadata/create-metadata-field)**：`string`、`number`、`time` のいずれかの型でカスタムフィールドを追加します。
* **[メタデータフィールドリストを取得](/ja/3.13.x/develop/api/metadata/list-metadata-fields)**：カスタムフィールドと組み込みフィールドの両方を、使用ドキュメント数とともに返します。
* **[メタデータフィールドを更新](/ja/3.13.x/develop/api/metadata/update-metadata-field)**：カスタムフィールドの名前を変更します。
* **[メタデータフィールドを削除](/ja/3.13.x/develop/api/metadata/delete-metadata-field)**：カスタムフィールドを削除します。対象ドキュメントはその値を失います。
* **[組み込みメタデータフィールドを取得](/ja/3.13.x/develop/api/metadata/get-built-in-metadata-fields)**：`document_name`、`uploader`、`upload_date` など、システム提供のフィールドを返します。
* **[組み込みメタデータフィールドを更新](/ja/3.13.x/develop/api/metadata/update-built-in-metadata-field)**：ナレッジベースごとに組み込みフィールドの有効・無効を切り替えます。
* **[ドキュメントメタデータを一括更新](/ja/3.13.x/develop/api/metadata/update-document-metadata-in-batch)**：1 回の呼び出しで複数のドキュメントにメタデータのキーと値を設定します。
メタデータは安定した外部キーとしても使えます。各ドキュメントにソースシステムの ID を保存しておけば、後続の同期実行でその ID をフィルタに使い、同じドキュメントを特定して更新できます。
## タグによるナレッジベースの整理
タグはワークスペース単位で管理され、個々のナレッジベースには依存しません。
* **[ナレッジベースタグを作成](/ja/3.13.x/develop/api/tags/create-knowledge-tag)**：ナレッジベースを整理するためのタグを作成します。
* **[ナレッジベースタグリストを取得](/ja/3.13.x/develop/api/tags/list-knowledge-tags)**：ワークスペース内のすべてのタグを返します。
* **[ナレッジベースタグを変更](/ja/3.13.x/develop/api/tags/update-knowledge-tag)**：タグの名前を変更します。
* **[ナレッジベースタグを削除](/ja/3.13.x/develop/api/tags/delete-knowledge-tag)**：紐づいていたすべてのナレッジベースからタグを外します。ナレッジベース自体は削除されません。
* **[タグをナレッジベースにバインド](/ja/3.13.x/develop/api/tags/create-tag-binding)**：1 つ以上のタグをナレッジベースにバインドします。1 つのナレッジベースに複数のタグを付けられます。
* **[タグとナレッジベースのバインドを解除](/ja/3.13.x/develop/api/tags/delete-tag-binding)**：ナレッジベースからタグを外します。
* **[ナレッジベースにバインドされたタグを取得](/ja/3.13.x/develop/api/tags/get-knowledge-base-tags)**：ナレッジベースに現在バインドされているタグを返します。
## 利用可能なモデルの取得
* **[利用可能なモデルを取得](/ja/3.13.x/develop/api/models/get-available-models)**：指定した `model_type` で利用できるモデルを返します。ナレッジベースの設定では、`text-embedding` で埋め込みモデルを、`rerank` でリランクモデルを照会します。
## ナレッジパイプラインの実行
ナレッジパイプラインは、データソースからデータを取り込みドキュメントに変換するワークフローです。
* **[パイプラインファイルをアップロード](/ja/3.13.x/develop/api/knowledge-pipeline/upload-pipeline-file)**：パイプラインが処理するファイルをアップロードします。
* **[データソースプラグインリストを取得](/ja/3.13.x/develop/api/knowledge-pipeline/list-datasource-plugins)**：パイプラインに設定されたデータソースノードを返します。既定では公開版を、`is_published=false` を指定すると下書き版を返します。
* **[データソースノードを実行](/ja/3.13.x/develop/api/knowledge-pipeline/run-datasource-node)**：単一のデータソースノードを実行し、結果をストリーミングで返します。1 つのステップを個別にテストする際に便利です。
* **[パイプラインを実行](/ja/3.13.x/develop/api/knowledge-pipeline/run-pipeline)**：`streaming` または `blocking` モードでパイプライン全体を実行します。`is_published` で公開版と下書きのどちらを実行するかを指定します。