Dify models and knowledge metadata Use this family to discover configured workspace models, define dataset metadata, enable built-in fields, or assign values to documents. All eight operations use one workspace-scoped knowledge credential. Metadata can expose document identity, upload history, source, and business attributes. Approval must bind each mutation to exact field identities, documents, replacement semantics, and readback evidence. Choose an operation | Operation suffix | Method and route | Purpose | Policy | | model.list | GET /v1/workspaces/current/models/model-types/{modeltype} | List configured models by type | Low-risk read; retry supported | | metadata.create | POST /v1/datasets/{datasetid}/metadata | Create one custom field | Medium mutation; approval and key required | | metadata.list | GET /v1/datasets/{datasetid}/metadata | List fields and usage counts | Low-risk read; retry supported | | metadata.update | PATCH /v1/datasets/{datasetid}/metadata/{metadataid} | Rename one custom field | Medium mutation; approval and key required | | metadata.delete | DELETE /v1/datasets/{datasetid}/metadata/{metadataid} | Delete a field and its values | High mutation; approval and key required | | metadata.builtin.list | GET /v1/datasets/{datasetid}/metadata/built-in | List built-in field definitions | Low-risk read; retry supported | | metadata.builtin.update | POST /v1/datasets/{datasetid}/metadata/built-in/{action} | Enable or disable built-ins | Medium mutation; approval and key required | | document.metadata.update | POST /v1/datasets/{datasetid}/documents/metadata | Update metadata for document entries | Medium mutation; approval and key required | These Tool operations have knowledge scope and no app-mode projection. The capability template is: cap:dify:knowledge:: The credential selects the workspace. Dataset and metadata route IDs must be provider UUIDs inside that workspace. Discover available models model.list accepts one of these modeltype values: • text-embedding • rerank • llm • tts • speech2text • moderation { "modeltype": "text-embedding" } The result contains data, grouped by provider. Provider entries expose identity, localized labels, configuration status, and model records. Use the returned provider and model identifiers when configuring knowledge bases or indexing. Discovery proves visibility at read time, not future quota, availability, quality, or successful invocation. Create and list custom fields metadata.create requires body.type and body.name. Type accepts string, number, or time. { "datasetid": "0190c42f-2d5a-7000-8000-000000000701", "body": { "type": "string", "name": "policyregion" } } The pinned service limits names to 255 characters. A name must be unique in the dataset and cannot equal a built-in field name. Apply a caller policy that also rejects blank or ambiguous names. Creation returns status 201 with id, type, and name. Persist the returned ID because document binding uses field identity, not only its visible name. metadata.list returns docmetadata and builtinfieldenabled. Each custom entry contains id, name, type, and the count of bound documents. Rename or delete a custom field Rename requires metadataid and a body name: { "datasetid": "0190c42f-2d5a-7000-8000-000000000701", "metadataid": "0190c42f-2d5a-7000-8000-000000000702", "body": { "name": "approvedregion" } } The provider migrates the metadata key across bound documents and keeps its value. The new name follows the same length, uniqueness, and built-in-name rules. metadata.delete removes the field, its bindings, and its values from related documents. Success returns empty status 204 and has no rollback contract. The pinned rename and delete helpers catch internal exceptions. A nominal response can therefore be insufficient evidence of the intended state. Always read metadata.list and affected documents after either mutation. Manage built-in fields metadata.builtin.list returns five static definitions: | Name | Type | | documentname | string | | uploader | string | | uploaddate | time | | lastupdatedate | time | | source | string | The definitions do not prove that built-in fields are enabled for the selected dataset. Read metadata.list for builtinfieldenabled. Set action to enable or disable: { "datasetid": "0190c42f-2d5a-7000-8000-000000000701", "action": "enable", "body": {} } Enable backfills those five values on working documents. Disable removes the keys and marks the dataset setting false. The pinned provider helper catches internal failures before returning result: success. Confirm the flag and sample affected documents after either action. Update document metadata document.metadata.update accepts body.operationdata. Each entry names one document, its field values, and whether the change is partial. { "datasetid": "0190c42f-2d5a-7000-8000-000000000701", "body": { "operationdata": [ { "documentid": "0190c42f-2d5a-7000-8000-000000000703", "metadatalist": [ { "id": "0190c42f-2d5a-7000-8000-000000000702", "name": "approvedregion", "value": "emea" } ], "partialupdate": true } ] } } Use the exact ID, name, and type from metadata.list. The provider uses the ID for its binding and the name for the stored document key. Mismatched identities can create misleading data. With partialupdate: true, Dify preserves unspecified metadata and bindings. With false, the default, it starts from an empty custom map and replaces the document's custom bindings with the supplied list. When built-ins are enabled, the provider restores their current values after either mode. A custom update cannot remove those five system fields. The provider commits each document entry separately. A later failure can leave earlier entries changed. The operation is not an atomic transaction across the whole array. Apply a tenant-policy count bound because the provider schema declares no route-specific maximum for operationdata. Read every intended document after the call before reporting batch success. Apply mutation governance All five mutations require a non-blank Action idempotency key of at most 512 bytes. AIP retains its tenant-scoped reservation for 24 hours and revalidates the input hash on collision. The key does not prove provider deduplication. These operations publish no automatic retry, cross-document transaction, reconciliation, cancellation, or compensation support. Treat model inventory, field definitions, document values, upload identities, sources, counts, and provider errors as confidential PII-bearing data. Redact them from general logs. Recover safely | Observation | Decision | | Route ID, model type, or body is rejected before dispatch | Correct the bounded request without claiming a provider effect | | Model is absent from discovery | Repair workspace provider configuration before selecting it | | Create response is lost | List fields by exact name and type before another create | | Rename returns no trustworthy record | Read the field list and affected document keys | | Delete returns 204 | Confirm the field and values are absent before closing the action | | Built-in toggle returns success | Confirm the dataset flag and sample document values | | Multi-document update fails partway | Read every intended document and reconcile only through new approvals | | Field ID and name no longer match | Refresh metadata discovery before another document mutation | | Returned data crosses a workspace or dataset boundary | Stop traffic and treat the event as an isolation incident | Preserve the Action ID, digest, approval, idempotency key, credential, dataset, field identities, document set, mode, and readback evidence needed to settle an ambiguous outcome. Related documentation • Dify capability index (README.md) • Dify knowledge documents and indexing (knowledge-documents-and-indexing.md) • Dify connector configuration (../reference/configuration.md) • Authentication and credential scopes (../getting-started/authentication-and-credential-scopes.md) • Errors and retry decisions (../../../reference/errors.md)