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 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

メタデータの内容が正しくありません。確認して検証してください

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

Last updated 10 months ago

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

hashtag使用方法

hashtagAPI呼び出しの例

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

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

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

hashtagナレッジベースリスト

hashtagナレッジベースの削除

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

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

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

hashtagドキュメントの削除

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

hashtag新しセグメントを増加

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

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

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

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

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

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

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

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

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

hashtagエラーメッセージ

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

使用方法

API呼び出しの例

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

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

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

ナレッジベースリスト

ナレッジベースの削除

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

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

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

ドキュメントの削除

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

新しセグメントを増加

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

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

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

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

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

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

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

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

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

エラーメッセージ