APIを活用したナレッジベースのメンテナンス

入門

マニュアル

ハンドオン工房

コミュニティ

プラグイン

開発

もっと読む

ポリシー

認証や呼び出し方法はサービスAPIと同様ですが、生成される各ナレッジベースAPIトークンには、現在のアカウントでアクセス可能なすべてのナレッジベースを操作する権限が付与されています。データの安全性には十分ご注意ください。

ナレッジベースAPI活用のメリット

APIによるナレッジベース管理はデータ処理効率を飛躍的に向上させます。コマンドラインからのデータ同期や自動化操作を容易に実現でき、UI操作の煩雑さから解放されます。

主なメリット：

自動同期: データシステムとDifyナレッジベースをシームレスに連携し、効率的なワークフローを構築。
総合管理: ナレッジベースリスト、ドキュメントリスト、詳細検索機能を提供し、カスタム管理インターフェースの構築が可能。
柔軟なアップロード: テキスト直接入力とファイルアップロードを両方サポート、チャンク単位の一括操作に対応。
生産性向上: 手動作業時間を削減し、Difyプラットフォームの利用体験を最適化。

使用方法

ナレッジベース管理画面左側ナビゲーションのAPIページにアクセス。APIドキュメントの閲覧や、APIキーによる認証情報の管理が可能です。

API呼び出しの例

テクストを通してドキュメントを作成する

入力例：

curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create-by-text' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{"name": "text","text": "text","indexing_technique": "high_quality","process_rule": {"mode": "automatic"}}'

出力例：

{
  "document": {
    "id": "",
    "position": 1,
    "data_source_type": "upload_file",
    "data_source_info": {
        "upload_file_id": ""
    },
    "dataset_process_rule_id": "",
    "name": "text.txt",
    "created_from": "api",
    "created_by": "",
    "created_at": 1695690280,
    "tokens": 0,
    "indexing_status": "waiting",
    "error": null,
    "enabled": true,
    "disabled_at": null,
    "disabled_by": null,
    "archived": false,
    "display_status": "queuing",
    "word_count": 0,
    "hit_count": 0,
    "doc_form": "text_model"
  },
  "batch": ""
}

ファイルを通してドキュメントを作成する

入力例：

curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create_by_file' \
--header 'Authorization: Bearer {api_key}' \
--form 'data="{"indexing_technique":"high_quality","process_rule":{"rules":{"pre_processing_rules":[{"id":"remove_extra_spaces","enabled":true},{"id":"remove_urls_emails","enabled":true}],"segmentation":{"separator":"###","max_tokens":500}},"mode":"custom"}}";type=text/plain' \
--form 'file=@"/path/to/file"'

出力例：

{
  "document": {
    "id": "",
    "position": 1,
    "data_source_type": "upload_file",
    "data_source_info": {
      "upload_file_id": ""
    },
    "dataset_process_rule_id": "",
    "name": "Dify.txt",
    "created_from": "api",
    "created_by": "",
    "created_at": 1695308667,
    "tokens": 0,
    "indexing_status": "waiting",
    "error": null,
    "enabled": true,
    "disabled_at": null,
    "disabled_by": null,
    "archived": false,
    "display_status": "queuing",
    "word_count": 0,
    "hit_count": 0,
    "doc_form": "text_model"
  },
  "batch": ""
}

空白のナレッジベースを作成する

空のデータセットを作成するためだけに使用

入力例：

curl --location --request POST 'https://api.dify.ai/v1/datasets' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{"name": "name", "permission": "only_me"}'

出力例：

{
  "id": "",
  "name": "name",
  "description": null,
  "provider": "vendor",
  "permission": "only_me",
  "data_source_type": null,
  "indexing_technique": null,
  "app_count": 0,
  "document_count": 0,
  "word_count": 0,
  "created_by": "",
  "created_at": 1695636173,
  "updated_by": "",
  "updated_at": 1695636173,
  "embedding_model": null,
  "embedding_model_provider": null,
  "embedding_available": null
}

ナレッジベースリスト

入力例：

curl --location --request GET 'https://api.dify.ai/v1/datasets?page=1&limit=20' \
--header 'Authorization: Bearer {api_key}'

出力例：

{
  "data": [
    {
      "id": "",
      "name": "ナレッジベースの名前",
      "description": "情報説明",
      "permission": "only_me",
      "data_source_type": "upload_file",
      "indexing_technique": "",
      "app_count": 2,
      "document_count": 10,
      "word_count": 1200,
      "created_by": "",
      "created_at": "",
      "updated_by": "",
      "updated_at": ""
    },
    ...
  ],
  "has_more": true,
  "limit": 20,
  "total": 50,
  "page": 1
}

ナレッジベースの削除

入力例：

curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}' \
--header 'Authorization: Bearer {api_key}'

出力例：

204 No Content

テクストを通してドキュメントを更新する

このAPIは存在しているナレッジベースにしか使えます。

入力例：

curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update_by_text' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{"name": "name","text": "text"}'

出力例：

{
  "document": {
    "id": "",
    "position": 1,
    "data_source_type": "upload_file",
    "data_source_info": {
      "upload_file_id": ""
    },
    "dataset_process_rule_id": "",
    "name": "name.txt",
    "created_from": "api",
    "created_by": "",
    "created_at": 1695308667,
    "tokens": 0,
    "indexing_status": "waiting",
    "error": null,
    "enabled": true,
    "disabled_at": null,
    "disabled_by": null,
    "archived": false,
    "display_status": "queuing",
    "word_count": 0,
    "hit_count": 0,
    "doc_form": "text_model"
  },
  "batch": ""
}

ファイルを通してドキュメントを更新する

このAPIは存在しているナレッジベースにしか使えます。

入力例：

curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update_by_file' \
--header 'Authorization: Bearer {api_key}' \
--form 'data="{"name":"Dify","indexing_technique":"high_quality","process_rule":{"rules":{"pre_processing_rules":[{"id":"remove_extra_spaces","enabled":true},{"id":"remove_urls_emails","enabled":true}],"segmentation":{"separator":"###","max_tokens":500}},"mode":"custom"}}";type=text/plain' \
--form 'file=@"/path/to/file"'

出力例：

{
  "document": {
    "id": "",
    "position": 1,
    "data_source_type": "upload_file",
    "data_source_info": {
      "upload_file_id": ""
    },
    "dataset_process_rule_id": "",
    "name": "Dify.txt",
    "created_from": "api",
    "created_by": "",
    "created_at": 1695308667,
    "tokens": 0,
    "indexing_status": "waiting",
    "error": null,
    "enabled": true,
    "disabled_at": null,
    "disabled_by": null,
    "archived": false,
    "display_status": "queuing",
    "word_count": 0,
    "hit_count": 0,
    "doc_form": "text_model"
  },
  "batch": "20230921150427533684"
}

ドキュメント埋め込みステータス(進捗状況)の取得

入力例：

curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{batch}/indexing-status' \
--header 'Authorization: Bearer {api_key}'

出力例：

{
  "data":[{
    "id": "",
    "indexing_status": "indexing",
    "processing_started_at": 1681623462.0,
    "parsing_completed_at": 1681623462.0,
    "cleaning_completed_at": 1681623462.0,
    "splitting_completed_at": 1681623462.0,
    "completed_at": null,
    "paused_at": null,
    "error": null,
    "stopped_at": null,
    "completed_segments": 24,
    "total_segments": 100
  }]
}

ドキュメント埋め込みステータス(進捗状況)の取得

入力例：

curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{batch}/indexing-status' \
--header 'Authorization: Bearer {api_key}'

出力例：

{
  "data":[{
    "id": "",
    "indexing_status": "indexing",
    "processing_started_at": 1681623462.0,
    "parsing_completed_at": 1681623462.0,
    "cleaning_completed_at": 1681623462.0,
    "splitting_completed_at": 1681623462.0,
    "completed_at": null,
    "paused_at": null,
    "error": null,
    "stopped_at": null,
    "completed_segments": 24,
    "total_segments": 100
  }]
}

ドキュメントの削除

入力例：

curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}' \
--header 'Authorization: Bearer {api_key}'

出力例：

{
  "result": "success"
}

ナレッジベースのドキュメントのリスト

入力例：

curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents' \
--header 'Authorization: Bearer {api_key}'

出力例：

{
  "data": [
    {
      "id": "",
      "position": 1,
      "data_source_type": "file_upload",
      "data_source_info": null,
      "dataset_process_rule_id": null,
      "name": "dify",
      "created_from": "",
      "created_by": "",
      "created_at": 1681623639,
      "tokens": 0,
      "indexing_status": "waiting",
      "error": null,
      "enabled": true,
      "disabled_at": null,
      "disabled_by": null,
      "archived": false
    },
  ],
  "has_more": false,
  "limit": 20,
  "total": 9,
  "page": 1
}

新しセグメントを増加

入力例：

curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{"segments": [{"content": "1","answer": "1","keywords": ["a"]}]}'

出力例：

{
  "data": [{
    "id": "",
    "position": 1,
    "document_id": "",
    "content": "1",
    "answer": "1",
    "word_count": 25,
    "tokens": 0,
    "keywords": [
        "a"
    ],
    "index_node_id": "",
    "index_node_hash": "",
    "hit_count": 0,
    "enabled": true,
    "disabled_at": null,
    "disabled_by": null,
    "status": "completed",
    "created_by": "",
    "created_at": 1695312007,
    "indexing_at": 1695312007,
    "completed_at": 1695312007,
    "error": null,
    "stopped_at": null
  }],
  "doc_form": "text_model"
}

ドキュメントのセグメントを見つける

入力例：

curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json'

出力例：

{
  "data": [{
    "id": "",
    "position": 1,
    "document_id": "",
    "content": "1",
    "answer": "1",
    "word_count": 25,
    "tokens": 0,
    "keywords": [
        "a"
    ],
    "index_node_id": "",
    "index_node_hash": "",
    "hit_count": 0,
    "enabled": true,
    "disabled_at": null,
    "disabled_by": null,
    "status": "completed",
    "created_by": "",
    "created_at": 1695312007,
    "indexing_at": 1695312007,
    "completed_at": 1695312007,
    "error": null,
    "stopped_at": null
  }],
  "doc_form": "text_model"
}

ドキュメントのセグメントの削除

入力例：

curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json'

出力例：

{
  "result": "success"
}

ドキュメントのセグメントの更新

入力例：

curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json'\
--data-raw '{"segment": {"content": "1","answer": "1", "keywords": ["a"], "enabled": false}}'

出力例：

{
  "data": [{
    "id": "",
    "position": 1,
    "document_id": "",
    "content": "1",
    "answer": "1",
    "word_count": 25,
    "tokens": 0,
    "keywords": [
        "a"
    ],
    "index_node_id": "",
    "index_node_hash": "",
    "hit_count": 0,
    "enabled": true,
    "disabled_at": null,
    "disabled_by": null,
    "status": "completed",
    "created_by": "",
    "created_at": 1695312007,
    "indexing_at": 1695312007,
    "completed_at": 1695312007,
    "error": null,
    "stopped_at": null
  }],
  "doc_form": "text_model"
}

ナレッジベースのメタデータフィールドを追加する

入力例：

curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {api_key}' \
--data '{
    "type":"string",
    "name":"test"
}'

出力例：

{
    "id": "9f63c91b-d60e-4142-bb0c-c81a54dc2db5",
    "type": "string",
    "name": "test"
}

ナレッジベースのメタデータフィールドを修正する

入力例：

curl --location --request PATCH 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/{metadata_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {api_key}' \
--data '{
    "name":"test"
}'

出力例：

{
    "id": "9f63c91b-d60e-4142-bb0c-c81a54dc2db5",
    "type": "string",
    "name": "test"
}

ナレッジベースのメタデータフィールドを削除する

入力例：

curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/{metadata_id}' \
--header 'Authorization: Bearer {api_key}'

出力例：

200 success

ナレッジベースのメタデータにある組み込みフィールドを有効化/無効化する

入力例：

curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/built-in/{action}' \
--header 'Authorization: Bearer {api_key}'

出力例：

200 success

ドキュメントのメタデータを修正する（値の割り当て）

入力例：

curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {api_key}'
--data '{
    "operation_data":[
        {
            "document_id": "3e928bc4-65ea-4201-87c8-cbcc5871f525",
            "metadata_list": [
                    {
                    "id": "1887f5ec-966f-4c93-8c99-5ad386022f46",
                    "value": "dify",
                    "name": "test"
                }
            ]
        }
    ]
}'

出力例：

200 success

データセットのメタデータリスト

入力例：

curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata' \
--header 'Authorization: Bearer {api_key}'

出力例：

{
  "doc_metadata": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "string",
      "name": "title",
      "use_count": 42
    },
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "type": "number",
      "name": "price",
      "use_count": 28
    },
    {
      "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c9",
      "type": "time",
      "name": "created_at",
      "use_count": 35
    }
  ],
  "built_in_field_enabled": true
}

エラーメッセージ

エラーメッセージ	エラーコード	理由
no_file_uploaded	400	ファイルをアップロードしてください
too_many_files	400	1つのファイルのみアップロードできます
file_too_large	413	ファイルサイズが制限を超えています
unsupported_file_type	415	サポートされていないファイルタイプです。現在、以下の形式のみをサポートしています：`txt`、 `markdown`、 `md`、 `pdf`、 `html`、 `xlsx`、 `docx`、 `csv`
high_quality_dataset_only	400	現在の操作は「高品質」のナレッジベースのみをサポートしています
dataset_not_initialized	400	ナレッジベースはまだ初期化中またはインデックス中です。お待ちください
archived_document_immutable	403	アーカイブされたドキュメントは編集できません
dataset_name_duplicate	409	ナレッジベース名がすでに存在します。ナレッジベース名を変更してください
invalid_action	400	無効な操作です
document_already_finished	400	ドキュメントの処理がすでに完了しています。ページを更新するか、ドキュメントの詳細を確認してください
document_indexing	400	ドキュメントが処理中のため、編集できません
invalid_metadata	400	メタデータの内容が正しくありません。確認して検証してください

このページを編集する

直接貢献することでドキュメントの改善にご協力ください

問題を報告する

エラーを見つけたり提案がありますか？お知らせください

ナレッジベース内のドキュメントの管理メタデータ

On this page

ナレッジベースAPI活用のメリット
使用方法
API呼び出しの例
テクストを通してドキュメントを作成する
ファイルを通してドキュメントを作成する
空白のナレッジベースを作成する
ナレッジベースリスト
ナレッジベースの削除
テクストを通してドキュメントを更新する
ファイルを通してドキュメントを更新する
ドキュメント埋め込みステータス(進捗状況)の取得
ドキュメント埋め込みステータス(進捗状況)の取得
ドキュメントの削除
ナレッジベースのドキュメントのリスト
新しセグメントを増加
ドキュメントのセグメントを見つける
ドキュメントのセグメントの削除
ドキュメントのセグメントの更新
ナレッジベースのメタデータフィールドを追加する
ナレッジベースのメタデータフィールドを修正する
ナレッジベースのメタデータフィールドを削除する
ナレッジベースのメタデータにある組み込みフィールドを有効化/無効化する
ドキュメントのメタデータを修正する（値の割り当て）
データセットのメタデータリスト
エラーメッセージ

入門

マニュアル

ハンドオン工房

コミュニティ

プラグイン

開発

もっと読む

ポリシー

​ナレッジベースAPI活用のメリット

​使用方法

​API呼び出しの例

​テクストを通してドキュメントを作成する

​ファイルを通してドキュメントを作成する

​空白のナレッジベースを作成する

​ナレッジベースリスト

​ナレッジベースの削除

​テクストを通してドキュメントを更新する

​ファイルを通してドキュメントを更新する

​ドキュメント埋め込みステータス(進捗状況)の取得

​ドキュメント埋め込みステータス(進捗状況)の取得

​ドキュメントの削除

​ナレッジベースのドキュメントのリスト

​新しセグメントを増加

​ドキュメントのセグメントを見つける

​ドキュメントのセグメントの削除

​ドキュメントのセグメントの更新

​ナレッジベースのメタデータフィールドを追加する

​ナレッジベースのメタデータフィールドを修正する

​ナレッジベースのメタデータフィールドを削除する

​ナレッジベースのメタデータにある組み込みフィールドを有効化/無効化する

​ドキュメントのメタデータを修正する（値の割り当て）

​データセットのメタデータリスト

​エラーメッセージ

このページを編集する

問題を報告する

ナレッジベースAPI活用のメリット

使用方法

API呼び出しの例

テクストを通してドキュメントを作成する

ファイルを通してドキュメントを作成する

空白のナレッジベースを作成する

ナレッジベースリスト

ナレッジベースの削除

テクストを通してドキュメントを更新する

ファイルを通してドキュメントを更新する

ドキュメント埋め込みステータス(進捗状況)の取得

ドキュメント埋め込みステータス(進捗状況)の取得

ドキュメントの削除

ナレッジベースのドキュメントのリスト

新しセグメントを増加

ドキュメントのセグメントを見つける

ドキュメントのセグメントの削除

ドキュメントのセグメントの更新

ナレッジベースのメタデータフィールドを追加する

ナレッジベースのメタデータフィールドを修正する

ナレッジベースのメタデータフィールドを削除する

ナレッジベースのメタデータにある組み込みフィールドを有効化/無効化する

ドキュメントのメタデータを修正する（値の割り当て）

データセットのメタデータリスト

エラーメッセージ