> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # ドキュメントメタデータを更新 > ドキュメントの `user_metadata` にキーをマージし、更新後のドキュメントを返します。このパスの他の操作とは異なり、ドキュメントファイル ID ではなくドキュメント ID を受け取ります。 ドキュメントの `row_version` を `expectedRowVersion` として送信します。更新の直前にドキュメントを読み取り、`409` が返った場合は読み直してから再送信してください。 ## OpenAPI ````yaml /ja/api-reference/openapi_service.json patch /knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id} openapi: 3.0.1 info: description: >- Dify アプリケーションとナレッジベースのための REST API です。アプリケーション系エンドポイントはアプリの API キーで、ナレッジ系エンドポイントはナレッジベースの API キーで認証します。 title: Dify サービス API version: 1.0.0 servers: - description: Dify サービス API のベース URL です。セルフホスト環境では、独自の API ベース URL に置き換えてください。 url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: API ベース URL のホストとパス（`https://` を除く）。 security: - ApiKeyAuth: [] tags: - description: チャットメッセージとインタラクションに関連する操作です。 name: チャットメッセージ - description: ファイルのアップロードとプレビューの操作です。 name: ファイル操作 - description: エンドユーザー情報に関連する操作です。 name: エンドユーザー - description: ユーザーフィードバックの操作です。 name: メッセージフィードバック - description: 会話管理に関連する操作です。 name: 会話管理 - description: テキスト読み上げと音声認識の操作です。 name: 音声・テキスト変換 - description: アプリケーション設定と情報を取得する操作です。 name: アプリケーション設定 - description: ダイレクト返信用のアノテーション管理に関連する操作です。 name: アノテーション管理 - description: 人間の入力を要する一時停止中のワークフローの再開操作です。 name: 人間の入力 - description: ワークフローの実行と管理のための操作です。 name: ワークフロー実行 - description: テキスト生成に関連する操作です。 name: 完了メッセージ - description: ナレッジベースの作成、設定、取得を含むナレッジベース管理の操作です。 name: ナレッジベース - description: ナレッジベース内のドキュメントの作成、更新、管理のための操作です。 name: ドキュメント - description: ドキュメントチャンクと子チャンクの管理のための操作です。 name: チャンク - description: ナレッジベースのメタデータフィールドとドキュメントメタデータ値の管理のための操作です。 name: メタデータ - description: ナレッジベースタグとタグバインディングの管理のための操作です。 name: タグ管理 - description: 利用可能なモデルを取得するための操作です。 name: モデル - description: データソースプラグインとパイプライン実行を含むナレッジパイプラインの管理と実行のための操作です。 name: ナレッジパイプライン - description: ナレッジベースに質問し、回答をストリーミングで受け取ります。 name: クエリ - description: クエリが何を検索したか、またその理由を確認します。 name: クエリ記録 - description: リサーチの質問をバックグラウンドで実行し、その結果を取得します。 name: リサーチタスク - description: ナレッジベースのドキュメントと、そのファイル、リビジョン、チャンクを読み取り、ドキュメントにメタデータのラベルを付けます。 name: ドキュメントとチャンク - description: インデックス処理の追跡、キャンセル、再試行と、ナレッジベースのバックグラウンドタスクの一覧表示を行います。 name: インデックスタスク - description: ドキュメントファイル、ファイルのバッチ、またはソースの削除を、完了するまで追跡します。 name: 削除ジョブ - description: ナレッジベースにデータを供給するソース、その同期スケジュール、接続を管理します。 name: ソース - description: ソースの即時同期、ウェブサイトのページまたはプロバイダーのアイテムのインポート、実行の追跡、キャンセル、再試行を行います。 name: ソースの同期とインポート - description: ナレッジベースのモデルと検索設定の読み取りと変更、および変更によって始まる移行の追跡を行います。 name: 設定 paths: /knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}: patch: tags: - Documents and Chunks summary: ドキュメントメタデータを更新 description: >- ドキュメントの `user_metadata` にキーをマージし、更新後のドキュメントを返します。このパスの他の操作とは異なり、ドキュメントファイル ID ではなくドキュメント ID を受け取ります。 ドキュメントの `row_version` を `expectedRowVersion` として送信します。更新の直前にドキュメントを読み取り、`409` が返った場合は読み直してから再送信してください。 operationId: updateDocumentMetadata parameters: - description: >- ナレッジベース ID です。ナレッジベースの **API アクセス** ダイアログに表示されるサービス API エンドポイントの最後のセグメント（`…/knowledge-fs/spaces/`）です。アドレスバーでは `/datasets/new/` の後のセグメントです。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- ドキュメント ID です。[ドキュメント一覧を取得](/ja/api-reference/documents-and-chunks/list-documents) または [ドキュメントを取得](/ja/api-reference/documents-and-chunks/get-document) の `id`、あるいは [ファイルからドキュメントを取得](/ja/api-reference/documents-and-chunks/get-document-by-file) の `document_id` を指定します。同じパスの [ドキュメントファイルを取得](/ja/api-reference/documents-and-chunks/get-document-file) と [ドキュメントファイルを削除](/ja/api-reference/documents-and-chunks/delete-document-file) はドキュメントファイル ID を受け取りますが、この操作は受け取りません。ドキュメントファイル ID を指定すると `404` が返ります。 in: path name: document_file_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: request: summary: リクエスト例 value: expectedRowVersion: 4 patch: owner: billing-team review_date: '2027-03-01T00:00:00Z' schema: additionalProperties: false properties: expectedRowVersion: description: >- ドキュメントの現在の `row_version` です。[ドキュメントを取得](/ja/api-reference/documents-and-chunks/get-document) または [ドキュメント一覧を取得](/ja/api-reference/documents-and-chunks/list-documents) から取得するか、この操作が最後に返した `row_version` を使用します。新しいリビジョンがアクティブになったときや、Dify でドキュメントを有効化または無効化したときにも変わるため、更新の直前に読み取ってください。古い値を送ると `409` が返り、何も変更されません。 minimum: 0 type: integer patch: additionalProperties: true description: >- `user_metadata` にマージするキー： - 値を指定したキーは、その値に設定されます。 - `null` を指定したキーは削除されます。 - 指定しなかったキーはそのまま残ります。 各キーには、メタデータフィールド名を小文字のスネークケースで指定します。フィールドは事前に存在している必要があるため、先に Dify で作成してください。値はフィールドの型に合わせます。`string` には文字列、`number` には有限の数値、`time` には `2026-12-01T00:00:00Z` のような UTC タイムスタンプを指定します。 次の予約済みキーを指定すると `400` が返ります：`activeRevision`、`contentHash`、`documentAssetId`、`documentAssetVersion`、`mimeType`、`provenance`、`providerItemId`、`sourceId`、`system`、`systemMetadata`、`tenantId`、`__knowledgeFs`、および `system.`、`provenance.`、`__knowledgeFs.` で始まるキー。 type: object required: - expectedRowVersion - patch type: object description: >- 正規化後のリクエストは、UTF-8 で 131,072 バイト以内に収める必要があります。[リクエストサイズの制限](/ja/api-reference/guides/knowledge-base#request-size-limits) を参照してください。 required: true responses: '200': content: application/json: examples: success: summary: レスポンス例 value: active: activated_at: '2026-10-20T08:16:05Z' content_hash: >- 4f7c2d9a1b3e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4 created_at: '2026-10-20T08:15:42Z' document_asset_id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b document_asset_version: 1 document_id: 2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b mime_type: application/pdf revision: 2 size_bytes: 482113 state: active active_revision: 2 created_at: '2026-09-03T10:02:11Z' disabled_at: null disabled_by_subject_id: null enabled: true id: 2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b latest_task: null provider_item_id: null row_version: 5 source_id: null status: ready title: handbook.pdf updated_at: '2026-10-21T02:40:13Z' user_metadata: owner: billing-team product_line: billing review_date: '2027-03-01T00:00:00Z' schema: $ref: '#/components/schemas/KnowledgeBaseDocument' description: >- 更新後のドキュメントです。この `row_version` を次回の更新で送信します。このレスポンスでは、`latest_task` は常に `null` です。 '400': content: application/json: examples: knowledge_fs_invalid_request_local: summary: knowledge_fs_invalid_request (request validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - patch type: missing knowledge_fs_invalid_request_path: summary: knowledge_fs_invalid_request (path ID) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (rejected) value: code: knowledge_fs_invalid_request failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`：リクエストが検証に失敗しました。`violations` には、問題のあるフィールドがそれぞれ示されます。`patch` または `expectedRowVersion` がない場合や、ボディにそれ以外のキーが含まれる場合は `400` が返ります。 - `knowledge_fs_invalid_request`：`patch` で予約済みキーを使用しているか、ナレッジベースにないメタデータフィールドを指定しているか、フィールドに誤った型の値を指定しています。エラー詳細はレスポンスボディの `failure` に入りますが、どのキーが拒否されたかは示されません。 - `knowledge_fs_invalid_request`：`document_file_id` が UUID ではありません。 - `knowledge_fs_invalid_request`：`document_file_id` の形式が正しくありません。 '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`：`Authorization` ヘッダーがないか、キーが不明であるか、ナレッジベースの API キーではありません。 - `knowledge_fs_invalid_credential`：キーは有効ですが、キーのワークスペースにこの ID のナレッジベースが存在しないか、キーがワークスペースに紐付いていません。 '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied_scope: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_upstream: summary: knowledge_fs_access_denied (rejected) value: code: knowledge_fs_access_denied failure: action: contact_admin category: authorization code: KNOWLEDGE_FS_ACCESS_DENIED message: >- You do not have permission to perform this Agent Knowledge Base operation. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- You do not have permission to perform this Agent Knowledge Base operation. status: 403 description: >- - `knowledge_fs_access_denied`：キーのアクセス範囲がほかのナレッジベースに限定されているか、このナレッジベースで **API アクセス** がオフになっています。または、ナレッジベースがアクティブではありません。 - `knowledge_fs_access_denied`：キーには、このナレッジベースのコンテンツへのアクセス権がありません。 - `forbidden`：Dify Cloud で、ワークスペースがサブスクリプションで定められたナレッジベースのリクエストレート制限に達しました。読み取りを含め、すべての呼び出しがカウントされます。 '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: >- - `knowledge_fs_resource_not_found`：この ID のドキュメントが存在しないか、API キーでは読み取れないか、ドキュメントのファイルまたはそのソースが削除中です。 - `not_found`：このデプロイ環境では Agent ナレッジベース機能が無効になっています。 '409': content: application/json: examples: logical_document_cas_conflict: summary: knowledge_fs_conflict (stale row version) value: code: knowledge_fs_conflict failure: action: retry category: conflict code: LOGICAL_DOCUMENT_CAS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. parameters: currentRowVersion: 5 expectedRowVersion: 4 retryPolicy: manual traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`：`expectedRowVersion` がドキュメントの現在の `row_version` と一致しません。新しいリビジョンがアクティブになった場合や、別の更新が先に反映された場合などに起こります。`failure.code` は `LOGICAL_DOCUMENT_CAS_CONFLICT` で、現在の値は `failure.parameters.currentRowVersion` に入ります。ドキュメントを読み直し、変更内容がまだ当てはまるかを確認してから、現在の `row_version` で再送信してください。 '413': content: application/json: examples: knowledge_fs_request_too_large: summary: knowledge_fs_request_too_large (request budget) value: code: knowledge_fs_request_too_large message: Agent Knowledge Base request is too large. status: 413 description: >- - `knowledge_fs_request_too_large`：Dify がデフォルト値を追加した後のリクエストが、UTF-8 で 131,072 バイトを超えています。[リクエストサイズの制限](/ja/api-reference/guides/knowledge-base#request-size-limits) を参照してください。 '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 knowledge_fs_upstream_unavailable_transport: summary: knowledge_fs_upstream_unavailable (no response) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`：時間内に応答が返らなかったか、応答を読み取れませんでした。 更新が反映されている可能性があります。再送信する前に、[ドキュメントを取得](/ja/api-reference/documents-and-chunks/get-document) でドキュメントを読み取り、`user_metadata` を比較してください。最初の呼び出しが反映されていた場合、古い `expectedRowVersion` で再送信すると `409` が返ります。 '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`：このワークスペースで Agent ナレッジベース機能が設定されていないか、このデプロイ環境ではこの操作を利用できません。または、リクエストの認可中に、このナレッジベースに対するキーのアクセス権が変更されました。 - `knowledge_fs_operation_unavailable`：現在このリクエストを処理できません。`failure.retryPolicy` に従ってください。 components: schemas: KnowledgeBaseDocument: properties: active: allOf: - $ref: '#/components/schemas/KnowledgeBaseDocumentRevision' description: >- アクティブなリビジョン、つまりナレッジベースが提供しているコンテンツです。その `revision` を [チャンク一覧を取得](/ja/api-reference/documents-and-chunks/list-chunks) に、`document_asset_id` を [ドキュメントファイルを取得](/ja/api-reference/documents-and-chunks/get-document-file) に渡します。アクティブなリビジョンがない間は `null` です。 nullable: true active_revision: description: アクティブなリビジョンの番号です。アクティブなリビジョンがない間は `null` です。 nullable: true type: integer created_at: description: ドキュメントの作成日時（ISO 8601）です。 type: string disabled_at: description: Dify でドキュメントが無効化された日時（ISO 8601）です。 nullable: true type: string disabled_by_subject_id: description: ドキュメントを無効化した操作者の内部 ID です。この API の呼び出しには不要です。 nullable: true type: string enabled: description: >- Dify でドキュメントが無効化されると `false` になります。[ドキュメントを再インデックス](/ja/api-reference/documents-and-chunks/re-index-documents) は、無効化されたドキュメントをスキップします。 type: boolean id: description: ドキュメント ID です。ドキュメントの内容を更新しても変わりません。 type: string knowledge_space_id: description: ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。 type: string latest_task: allOf: - $ref: '#/components/schemas/KnowledgeBaseBackgroundTask' description: >- ドキュメントのリビジョンを作成した最新のインデックスタスクで、`task_kind: document` を持ちます。その `id` を指定して [ドキュメントのインデックスタスクを取得](/ja/api-reference/indexing-tasks/get-document-indexing-task) で追跡します。タスクがない場合は `null` です。[ドキュメントメタデータを更新](/ja/api-reference/documents-and-chunks/update-document-metadata) のレスポンスでは常に `null` です。 nullable: true provider_item_id: description: >- ソースからインポートしたドキュメントの場合、ソース側でのアイテムの識別子です。[ソースのアイテムをインポート](/ja/api-reference/source-syncs-and-imports/import-source-items) に送信した `providerItemId`、またはウェブサイトのページの `page_id` です。 nullable: true type: string row_version: description: >- 変更カウンターです。[ドキュメントメタデータを更新](/ja/api-reference/documents-and-chunks/update-document-metadata) で `expectedRowVersion` として送信します。メタデータの更新時、新しいリビジョンがアクティブになった時、Dify でドキュメントが有効化または無効化された時に増加します。 type: integer source_id: description: ドキュメントの取得元のソースです。アップロードされたファイルでは `null` です。 nullable: true type: string status: description: >- `pending`（まだアクティブなリビジョンがない）、`ready`（リビジョンがアクティブ）、`failed`（最初のリビジョンのインデックス処理に失敗し、アクティブなリビジョンがない）、`deleting` のいずれかです。`ready` のドキュメントは、後続のリビジョンが失敗しても `ready` のままです。 type: string title: description: ドキュメントのタイトルです。 type: string updated_at: description: ドキュメントが最後に変更された日時（ISO 8601）です。 type: string user_metadata: additionalProperties: true description: >- カスタムメタデータで、キーはメタデータフィールド名です。[ドキュメントメタデータを更新](/ja/api-reference/documents-and-chunks/update-document-metadata) または Dify で変更できます。 type: object type: object KnowledgeBaseDocumentRevision: properties: activated_at: description: リビジョンがアクティブになった日時（ISO 8601）です。一度もアクティブになっていないリビジョンでは `null` です。 nullable: true type: string content_hash: description: コンテンツの SHA-256 ハッシュ（16 進数エンコード）です。 type: string created_at: description: リビジョンの作成日時（ISO 8601）です。 type: string document_asset_id: description: >- このリビジョンの元になったドキュメントファイルの ID です。[ドキュメントファイルを取得](/ja/api-reference/documents-and-chunks/get-document-file) で使用します。 type: string document_asset_version: description: このリビジョンが作成された時点での、ドキュメントファイルの `version` です。 type: integer document_id: description: >- ドキュメント ID です。[ドキュメントを取得](/ja/api-reference/documents-and-chunks/get-document) の `id` にあたります。 type: string knowledge_space_id: description: ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。 type: string mime_type: description: ドキュメントファイルの MIME タイプです。 type: string revision: description: >- リビジョン番号で、`1` から始まります。[チャンク一覧を取得](/ja/api-reference/documents-and-chunks/list-chunks) のパスパラメータ `revision` に指定する値です。 type: integer size_bytes: description: ドキュメントファイルのサイズ（バイト単位）です。 type: integer state: description: >- インデックス処理中のリビジョンは `candidate`、ナレッジベースが提供しているリビジョンは `active` です。新しいリビジョンがアクティブになった後は `superseded`、インデックス処理に失敗した場合は `failed` になります。 type: string type: object KnowledgeBaseBackgroundTask: properties: can_cancel: description: >- タスクを現時点でキャンセルできるかどうかです。`task_kind: document` の場合は、`id` を指定して [インデックスタスクをキャンセル](/ja/api-reference/indexing-tasks/cancel-indexing-task) でキャンセルします。一括タスクには、`can_cancel` が `true` であっても、この API でキャンセルする操作はありません。 type: boolean can_retry: description: >- タスクを現時点で再試行できるかどうかです。`task_kind: document` の場合は、`id` を指定して [インデックスタスクを再試行](/ja/api-reference/indexing-tasks/retry-indexing-task) で再試行します。この操作が受け付けるのは `failed` または `canceled` のタスクのみです。一方、`can_retry` は、セマンティックエンリッチメントが失敗した `completed` のインデックスタスクでも `true` になります。 type: boolean completed_at: description: タスクの終了日時（ISO 8601）です。実行中は `null` です。 nullable: true type: string created_at: description: タスクの作成日時（ISO 8601）です。 type: string document_id: description: インデックスタスクのドキュメント ID です。一括タスクでは、対象ドキュメントが 1 件の場合にのみ設定されます。 nullable: true type: string document_revision: description: インデックスタスクが構築するリビジョンです。 nullable: true type: integer document_title: description: ドキュメントのタイトルです。対象ドキュメントが 1 件の一括タスクでのみ設定されます。 nullable: true type: string error_code: description: '`state` が `failed` の場合のエラーコードです。' nullable: true type: string error_message: description: '`error_code` に対応するメッセージです。`failure.message` と異なる場合があります。' nullable: true type: string failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: '`state` が `failed` の場合のエラー詳細です。それ以外の場合は `null` です。' nullable: true failures: description: 一括タスクの場合、失敗したドキュメントごとに 1 つのエントリが入ります。ほかの種類では `null` です。 items: properties: document_id: description: ドキュメント ID です。 type: string document_title: description: ドキュメントのタイトルです。 nullable: true type: string error_code: description: 失敗のエラーコードです。 type: string error_message: description: '`error_code` に対応するメッセージです。' type: string failure: $ref: '#/components/schemas/KnowledgeBaseErrorDetails' job_id: description: ドキュメントに対応するタスクの ID です（存在する場合）。 nullable: true type: string type: object nullable: true type: array id: description: >- タスク ID です。`task_kind: document` ではインデックスタスク ID、`document_bulk` では一括タスク ID、`source` ではソースの実行 ID です。 type: string knowledge_space_id: description: ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。 type: string operation: description: >- タスクの処理内容です： - `document_processing`：インデックスタスクです。 - `document_reindex`、`document_upload`、`document_delete`：一括タスクです。一括アップロードと一括削除は Dify 上で実行されたものです。この API で削除した場合は、代わりに削除ジョブが作成されます。 - `source_sync`、`source_crawl_preview`、`source_crawl_import`、`source_online_document_import`、`source_online_drive_import`：ソースの実行です。 type: string progress_completed: description: 完了したアイテム数です。インデックスタスクではそのドキュメント、一括タスクでは各ドキュメント、ソースの実行では各アイテムを数えます。 type: integer progress_failed: description: 失敗したアイテム数です。数え方は `progress_completed` と同じです。 type: integer progress_percent: description: 0 から 100 までの進捗です。インデックスタスクでは、タスクの段階に応じて進みます。 type: integer progress_total: description: タスク内のアイテム数です。数え方は `progress_completed` と同じです。インデックスタスクでは `1` です。 type: integer semantic_enrichment: allOf: - $ref: '#/components/schemas/KnowledgeBaseSemanticEnrichment' description: >- インデックスタスクのコンテンツに対するナレッジグラフの構築ステータスです。詳細検索とリサーチ検索は、ナレッジグラフをたどります。ほかの種類では `null` です。 nullable: true source_id: description: ソースの実行が属するソースです。 nullable: true type: string source_title: description: ソースの実行が属するソースの名前です。`task_ids` を指定せずに一覧を取得した場合にのみ設定されます。 nullable: true type: string state: description: >- `queued`、`running`、`completed`、`failed`、`canceled` のいずれかで、各タスク固有の状態から変換されます： - インデックスタスクは、公開が済んだ時点で `completed` になります。セマンティックエンリッチメントがまだ実行中でも同様です。 - ページの選択を待っているクロールプレビューは `completed` です。 正確な状態は、インデックスタスクなら [インデックスタスクを取得](/ja/api-reference/indexing-tasks/get-indexing-task)、ソースの実行なら [ソースの実行を取得](/ja/api-reference/source-syncs-and-imports/get-source-run) で確認してください。 type: string task_kind: description: >- `document`（インデックスタスク）、`document_bulk`（一括タスク）、`source`（ソースの実行）のいずれかです。 type: string updated_at: description: タスクが最後に変更された日時（ISO 8601）です。 type: string type: object KnowledgeBaseErrorDetails: properties: action: description: >- 推奨される次の対応です。ある場合は `configure_model`、`configure_parser`、`configure_source`、`contact_admin`、`reupload`、`retry` のいずれかです。該当しない場合は `null` で、HTTP エラーのボディでは省略されます。 nullable: true type: string category: description: >- 失敗の種類で、`authorization`、`canceled`、`configuration`、`conflict`、`dependency`、`internal`、`not_found`、`rate_limit`、`timeout`、`validation` のいずれかです。 type: string code: description: >- 大文字のスネークケースで表される固定のエラーコードです（例：`KNOWLEDGE_FS_CONFLICT`、`SOURCE_CREDENTIAL_TEST_FAILED`）。 type: string message: description: エラーコードまたは失敗の種類に対応する公開用メッセージです。プロバイダーのエラー詳細は公開されません。 type: string parameters: additionalProperties: true description: >- 失敗の内容を補足する最大 8 個の値です。キーは `attempt`、`currentRowVersion`、`documentCount`、`expectedRowVersion`、`fileSizeBytes`、`limit`、`maxFileSizeBytes`、`maxItems`、`modelType`、`providerKind`、`retryAfterSeconds`、`status` のいずれかです。値がない場合は `null` で、HTTP エラーのボディでは省略されます。 nullable: true type: object retryPolicy: description: >- 再試行で解決できるかどうかです。`automatic`（サービスが自動で再試行）、`manual`（呼び出し側で再試行）、`after_configuration`（先に Dify でナレッジベースの設定を修正）、`never`（リクエストを変更）のいずれかです。 type: string stage: description: >- 失敗が発生した段階です（例：`query_generation`、`credential-test`）。該当しない場合は `null` で、HTTP エラーのボディでは省略されます。 nullable: true type: string traceId: description: >- 管理者に問い合わせる際に伝える参照情報です。失敗の詳細を含む成功レスポンスでは `null` になることがあり、HTTP エラーのボディでは省略されることがあります。 nullable: true type: string type: object KnowledgeBaseSemanticEnrichment: properties: error_code: description: '`state` が `failed` の場合のエラーコードです。' nullable: true type: string error_message: description: '`error_code` に対応するメッセージです。`failure.message` と異なる場合があります。' nullable: true type: string failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: '`state` が `failed` の場合のエラー詳細です。それ以外の場合は `null` です。' nullable: true nodes_completed: description: >- 構築済みのナレッジグラフのノード数です。`state` が `ready` になるまでは `0` で、その後は `nodes_total` と同じ値になります。 type: integer nodes_total: description: 構築するナレッジグラフのノード数です。判明するまでは `null` です。 nullable: true type: integer provider_calls: description: これまでのモデル呼び出し回数です。 nullable: true type: integer provider_calls_maximum: description: ナレッジグラフの構築で実行できるモデル呼び出しの最大回数です。 nullable: true type: integer state: description: >- `not_scheduled`、`pending`、`running`、`ready`、`failed`、`disabled` のいずれかです。インデックスタスクがリビジョンを公開した後も、ナレッジグラフの構築が `pending` または `running` のままの場合があります。 type: string updated_at: description: エンリッチメントが最後に変更された日時（ISO 8601）です。 nullable: true type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- すべてのリクエストは API キーで認証します：`Authorization: Bearer {API_KEY}`。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（[Dify API クイックスタート](/ja/api-reference/guides/get-started)）。 キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP `401`（`unauthorized`）で失敗します。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.