ドキュメントメタデータを更新
ドキュメントの user_metadata にキーをマージし、更新後のドキュメントを返します。このパスの他の操作とは異なり、ドキュメントファイル ID ではなくドキュメント ID を受け取ります。
ドキュメントの row_version を expectedRowVersion として送信します。更新の直前にドキュメントを読み取り、409 が返った場合は読み直してから再送信してください。
curl --request PATCH \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"expectedRowVersion": 4,
"patch": {
"owner": "billing-team",
"review_date": "2027-03-01T00:00:00Z"
}
}
'import requests
url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}"
payload = {
"expectedRowVersion": 4,
"patch": {
"owner": "billing-team",
"review_date": "2027-03-01T00:00:00Z"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
expectedRowVersion: 4,
patch: {owner: 'billing-team', review_date: '2027-03-01T00:00:00Z'}
})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'expectedRowVersion' => 4,
'patch' => [
'owner' => 'billing-team',
'review_date' => '2027-03-01T00:00:00Z'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}"
payload := strings.NewReader("{\n \"expectedRowVersion\": 4,\n \"patch\": {\n \"owner\": \"billing-team\",\n \"review_date\": \"2027-03-01T00:00:00Z\"\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expectedRowVersion\": 4,\n \"patch\": {\n \"owner\": \"billing-team\",\n \"review_date\": \"2027-03-01T00:00:00Z\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expectedRowVersion\": 4,\n \"patch\": {\n \"owner\": \"billing-team\",\n \"review_date\": \"2027-03-01T00:00:00Z\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}Authorizations
すべてのリクエストは API キーで認証します：Authorization: Bearer {API_KEY}。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（Dify API クイックスタート）。
キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP 401（unauthorized）で失敗します。
Path Parameters
ナレッジベース ID です。ナレッジベースの API アクセス ダイアログに表示されるサービス API エンドポイントの最後のセグメント（…/knowledge-fs/spaces/<knowledge base ID>）です。アドレスバーでは /datasets/new/ の後のセグメントです。
ドキュメント ID です。ドキュメント一覧を取得 または ドキュメントを取得 の id、あるいは ファイルからドキュメントを取得 の document_id を指定します。同じパスの ドキュメントファイルを取得 と ドキュメントファイルを削除 はドキュメントファイル ID を受け取りますが、この操作は受け取りません。ドキュメントファイル ID を指定すると 404 が返ります。
Body
正規化後のリクエストは、UTF-8 で 131,072 バイト以内に収める必要があります。リクエストサイズの制限 を参照してください。
ドキュメントの現在の row_version です。ドキュメントを取得 または ドキュメント一覧を取得 から取得するか、この操作が最後に返した row_version を使用します。新しいリビジョンがアクティブになったときや、Dify でドキュメントを有効化または無効化したときにも変わるため、更新の直前に読み取ってください。古い値を送ると 409 が返り、何も変更されません。
x >= 0user_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. で始まるキー。
Response
更新後のドキュメントです。この row_version を次回の更新で送信します。このレスポンスでは、latest_task は常に null です。
アクティブなリビジョン、つまりナレッジベースが提供しているコンテンツです。その revision を チャンク一覧を取得 に、document_asset_id を ドキュメントファイルを取得 に渡します。アクティブなリビジョンがない間は null です。
Show child attributes
Show child attributes
アクティブなリビジョンの番号です。アクティブなリビジョンがない間は null です。
ドキュメントの作成日時（ISO 8601）です。
Dify でドキュメントが無効化された日時（ISO 8601）です。
ドキュメントを無効化した操作者の内部 ID です。この API の呼び出しには不要です。
Dify でドキュメントが無効化されると false になります。ドキュメントを再インデックス は、無効化されたドキュメントをスキップします。
ドキュメント ID です。ドキュメントの内容を更新しても変わりません。
ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。
ドキュメントのリビジョンを作成した最新のインデックスタスクで、task_kind: document を持ちます。その id を指定して ドキュメントのインデックスタスクを取得 で追跡します。タスクがない場合は null です。ドキュメントメタデータを更新 のレスポンスでは常に null です。
Show child attributes
Show child attributes
ソースからインポートしたドキュメントの場合、ソース側でのアイテムの識別子です。ソースのアイテムをインポート に送信した providerItemId、またはウェブサイトのページの page_id です。
変更カウンターです。ドキュメントメタデータを更新 で expectedRowVersion として送信します。メタデータの更新時、新しいリビジョンがアクティブになった時、Dify でドキュメントが有効化または無効化された時に増加します。
ドキュメントの取得元のソースです。アップロードされたファイルでは null です。
pending（まだアクティブなリビジョンがない）、ready（リビジョンがアクティブ）、failed（最初のリビジョンのインデックス処理に失敗し、アクティブなリビジョンがない）、deleting のいずれかです。ready のドキュメントは、後続のリビジョンが失敗しても ready のままです。
ドキュメントのタイトルです。
ドキュメントが最後に変更された日時（ISO 8601）です。
カスタムメタデータで、キーはメタデータフィールド名です。ドキュメントメタデータを更新 または Dify で変更できます。
Was this page helpful?
curl --request PATCH \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"expectedRowVersion": 4,
"patch": {
"owner": "billing-team",
"review_date": "2027-03-01T00:00:00Z"
}
}
'import requests
url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}"
payload = {
"expectedRowVersion": 4,
"patch": {
"owner": "billing-team",
"review_date": "2027-03-01T00:00:00Z"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
expectedRowVersion: 4,
patch: {owner: 'billing-team', review_date: '2027-03-01T00:00:00Z'}
})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'expectedRowVersion' => 4,
'patch' => [
'owner' => 'billing-team',
'review_date' => '2027-03-01T00:00:00Z'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}"
payload := strings.NewReader("{\n \"expectedRowVersion\": 4,\n \"patch\": {\n \"owner\": \"billing-team\",\n \"review_date\": \"2027-03-01T00:00:00Z\"\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expectedRowVersion\": 4,\n \"patch\": {\n \"owner\": \"billing-team\",\n \"review_date\": \"2027-03-01T00:00:00Z\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expectedRowVersion\": 4,\n \"patch\": {\n \"owner\": \"billing-team\",\n \"review_date\": \"2027-03-01T00:00:00Z\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}