Skip to main content
PATCH
Update Document Metadata

Authorizations

Authorization
string
header
required

Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Path Parameters

knowledge_base_id
string<uuid>
required

Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.

document_file_id
string<uuid>
required

The document ID: id from List Documents or Get Document, or document_id from Get Document by File. Not a document file ID, even though Get Document File and Delete Document File take one on this path. A document file ID answers 404.

Body

application/json

The normalized request must fit within 131,072 UTF-8 bytes. See Request Size Limits.

expectedRowVersion
integer
required

The document's current row_version, from Get Document or List Documents, or the row_version this operation last returned. A newly active revision and enabling or disabling the document in Dify also change it, so read it right before updating. A stale value answers 409 and nothing changes.

Required range: x >= 0
patch
object
required

Keys to merge into user_metadata:

  • A key with a value sets that key.
  • A key with null removes it.
  • Keys you leave out stay as they are.

Each key names a metadata field, in lowercase snake case. The field must already exist: create it in Dify first. The value must match the field's type: a string for string, a finite number for number, and a UTC timestamp such as 2026-12-01T00:00:00Z for time.

Reserved keys answer 400: activeRevision, contentHash, documentAssetId, documentAssetVersion, mimeType, provenance, providerItemId, sourceId, system, systemMetadata, tenantId, __knowledgeFs, and keys starting with system., provenance., or __knowledgeFs..

Response

The updated document. Its row_version is the value to send on the next update, and latest_task is always null in this response.

active
object | null

The active revision: the content the knowledge base serves. Pass its revision to List Chunks and its document_asset_id to Get Document File. null while no revision is active.

active_revision
integer | null

Number of the active revision. null while none is active.

created_at
string

When the document was created, ISO 8601.

disabled_at
string | null

When the document was disabled in Dify, ISO 8601.

disabled_by_subject_id
string | null

Internal ID of whoever disabled the document. Not needed to call this API.

enabled
boolean

false after the document is disabled in Dify. Re-index Documents skips disabled documents.

id
string

Document ID. It stays the same when the document's content is updated.

knowledge_space_id
string

Internal ID of the knowledge base. Not the knowledge base ID in the path.

latest_task
object | null

The newest indexing task behind the document's revisions, with task_kind: document. Follow it with Get Document Indexing Task using its id. null when there is none, and always null in the Update Document Metadata response.

provider_item_id
string | null

For a document imported from a source, the item's identifier there: the providerItemId sent to Import Source Items, or the page_id of a website page.

row_version
integer

Change counter. Send it as expectedRowVersion on Update Document Metadata. It increases on metadata updates, when a new revision becomes active, and when the document is enabled or disabled in Dify.

source_id
string | null

Source the document came from. null for uploaded files.

status
string

pending (no revision active yet), ready (a revision is active), failed (the first revision failed to index and none is active), or deleting. A ready document stays ready when a later revision fails.

title
string

Document title.

updated_at
string

When the document last changed, ISO 8601.

user_metadata
object

Custom metadata, keyed by metadata field name. Change it with Update Document Metadata or in Dify.