{
  "schemaVersion": "1.0",
  "title": "Dify models and knowledge metadata",
  "description": "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.",
  "canonical": "https://getaip.org/docs/connectors/dify/capabilities/knowledge-metadata-and-models",
  "route": "/docs/connectors/dify/capabilities/knowledge-metadata-and-models",
  "source": "docs/connectors/dify/capabilities/knowledge-metadata-and-models.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/dify/capabilities/knowledge-metadata-and-models.md",
    "txt": "/docs/download/connectors/dify/capabilities/knowledge-metadata-and-models.txt",
    "json": "/docs/download/connectors/dify/capabilities/knowledge-metadata-and-models.json",
    "pdf": "/docs/download/connectors/dify/capabilities/knowledge-metadata-and-models.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Dify models and knowledge metadata\ndescription: >-\n  Discover workspace models and maintain dataset and document metadata through\n  the frozen Dify connector\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\n---\n\n# Dify models and knowledge metadata\n\nUse this family to discover configured workspace models, define dataset\nmetadata, enable built-in fields, or assign values to documents. All eight\noperations use one workspace-scoped knowledge credential.\n\nMetadata can expose document identity, upload history, source, and business\nattributes. Approval must bind each mutation to exact field identities,\ndocuments, replacement semantics, and readback evidence.\n\n## Choose an operation\n\n| Operation suffix | Method and route | Purpose | Policy |\n|---|---|---|---|\n| `model.list` | `GET /v1/workspaces/current/models/model-types/{model_type}` | List configured models by type | Low-risk read; retry supported |\n| `metadata.create` | `POST /v1/datasets/{dataset_id}/metadata` | Create one custom field | Medium mutation; approval and key required |\n| `metadata.list` | `GET /v1/datasets/{dataset_id}/metadata` | List fields and usage counts | Low-risk read; retry supported |\n| `metadata.update` | `PATCH /v1/datasets/{dataset_id}/metadata/{metadata_id}` | Rename one custom field | Medium mutation; approval and key required |\n| `metadata.delete` | `DELETE /v1/datasets/{dataset_id}/metadata/{metadata_id}` | Delete a field and its values | High mutation; approval and key required |\n| `metadata.builtin.list` | `GET /v1/datasets/{dataset_id}/metadata/built-in` | List built-in field definitions | Low-risk read; retry supported |\n| `metadata.builtin.update` | `POST /v1/datasets/{dataset_id}/metadata/built-in/{action}` | Enable or disable built-ins | Medium mutation; approval and key required |\n| `document.metadata.update` | `POST /v1/datasets/{dataset_id}/documents/metadata` | Update metadata for document entries | Medium mutation; approval and key required |\n\nThese Tool operations have knowledge scope and no app-mode projection. The\ncapability template is:\n\n```text\ncap:dify:knowledge:<credential_id>:<operation>\n```\n\nThe credential selects the workspace. Dataset and metadata route IDs must be\nprovider UUIDs inside that workspace.\n\n## Discover available models\n\n`model.list` accepts one of these `model_type` values:\n\n- `text-embedding`\n- `rerank`\n- `llm`\n- `tts`\n- `speech2text`\n- `moderation`\n\n```json\n{\n  \"model_type\": \"text-embedding\"\n}\n```\n\nThe result contains `data`, grouped by provider. Provider entries expose\nidentity, localized labels, configuration status, and model records.\n\nUse the returned provider and model identifiers when configuring knowledge\nbases or indexing. Discovery proves visibility at read time, not future quota,\navailability, quality, or successful invocation.\n\n## Create and list custom fields\n\n`metadata.create` requires `body.type` and `body.name`. Type accepts `string`,\n`number`, or `time`.\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000701\",\n  \"body\": {\n    \"type\": \"string\",\n    \"name\": \"policy_region\"\n  }\n}\n```\n\nThe pinned service limits names to 255 characters. A name must be unique in\nthe dataset and cannot equal a built-in field name. Apply a caller policy that\nalso rejects blank or ambiguous names.\n\nCreation returns status 201 with `id`, `type`, and `name`. Persist the returned\nID because document binding uses field identity, not only its visible name.\n\n`metadata.list` returns `doc_metadata` and `built_in_field_enabled`. Each custom\nentry contains `id`, `name`, `type`, and the count of bound documents.\n\n## Rename or delete a custom field\n\nRename requires `metadata_id` and a body `name`:\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000701\",\n  \"metadata_id\": \"0190c42f-2d5a-7000-8000-000000000702\",\n  \"body\": {\n    \"name\": \"approved_region\"\n  }\n}\n```\n\nThe provider migrates the metadata key across bound documents and keeps its\nvalue. The new name follows the same length, uniqueness, and built-in-name\nrules.\n\n`metadata.delete` removes the field, its bindings, and its values from related\ndocuments. Success returns empty status 204 and has no rollback contract.\n\nThe pinned rename and delete helpers catch internal exceptions. A nominal\nresponse can therefore be insufficient evidence of the intended state. Always\nread `metadata.list` and affected documents after either mutation.\n\n## Manage built-in fields\n\n`metadata.builtin.list` returns five static definitions:\n\n| Name | Type |\n|---|---|\n| `document_name` | `string` |\n| `uploader` | `string` |\n| `upload_date` | `time` |\n| `last_update_date` | `time` |\n| `source` | `string` |\n\nThe definitions do not prove that built-in fields are enabled for the selected\ndataset. Read `metadata.list` for `built_in_field_enabled`.\n\nSet `action` to `enable` or `disable`:\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000701\",\n  \"action\": \"enable\",\n  \"body\": {}\n}\n```\n\nEnable backfills those five values on working documents. Disable removes the\nkeys and marks the dataset setting false.\n\nThe pinned provider helper catches internal failures before returning\n`result: success`. Confirm the flag and sample affected documents after either\naction.\n\n## Update document metadata\n\n`document.metadata.update` accepts `body.operation_data`. Each entry names one\ndocument, its field values, and whether the change is partial.\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000701\",\n  \"body\": {\n    \"operation_data\": [\n      {\n        \"document_id\": \"0190c42f-2d5a-7000-8000-000000000703\",\n        \"metadata_list\": [\n          {\n            \"id\": \"0190c42f-2d5a-7000-8000-000000000702\",\n            \"name\": \"approved_region\",\n            \"value\": \"emea\"\n          }\n        ],\n        \"partial_update\": true\n      }\n    ]\n  }\n}\n```\n\nUse the exact ID, name, and type from `metadata.list`. The provider uses the ID\nfor its binding and the name for the stored document key. Mismatched identities\ncan create misleading data.\n\nWith `partial_update: true`, Dify preserves unspecified metadata and bindings.\nWith false, the default, it starts from an empty custom map and replaces the\ndocument's custom bindings with the supplied list.\n\nWhen built-ins are enabled, the provider restores their current values after\neither mode. A custom update cannot remove those five system fields.\n\nThe provider commits each document entry separately. A later failure can leave\nearlier entries changed. The operation is not an atomic transaction across the\nwhole array.\n\nApply a tenant-policy count bound because the provider schema declares no\nroute-specific maximum for `operation_data`. Read every intended document after\nthe call before reporting batch success.\n\n## Apply mutation governance\n\nAll five mutations require a non-blank Action idempotency key of at most 512\nbytes. AIP retains its tenant-scoped reservation for 24 hours and revalidates\nthe input hash on collision.\n\nThe key does not prove provider deduplication. These operations publish no\nautomatic retry, cross-document transaction, reconciliation, cancellation, or\ncompensation support.\n\nTreat model inventory, field definitions, document values, upload identities,\nsources, counts, and provider errors as confidential PII-bearing data. Redact\nthem from general logs.\n\n## Recover safely\n\n| Observation | Decision |\n|---|---|\n| Route ID, model type, or body is rejected before dispatch | Correct the bounded request without claiming a provider effect |\n| Model is absent from discovery | Repair workspace provider configuration before selecting it |\n| Create response is lost | List fields by exact name and type before another create |\n| Rename returns no trustworthy record | Read the field list and affected document keys |\n| Delete returns 204 | Confirm the field and values are absent before closing the action |\n| Built-in toggle returns success | Confirm the dataset flag and sample document values |\n| Multi-document update fails partway | Read every intended document and reconcile only through new approvals |\n| Field ID and name no longer match | Refresh metadata discovery before another document mutation |\n| Returned data crosses a workspace or dataset boundary | Stop traffic and treat the event as an isolation incident |\n\nPreserve the Action ID, digest, approval, idempotency key, credential, dataset,\nfield identities, document set, mode, and readback evidence needed to settle an\nambiguous outcome.\n\n## Related documentation\n\n- [Dify capability index](README.md)\n- [Dify knowledge documents and indexing](knowledge-documents-and-indexing.md)\n- [Dify connector configuration](../reference/configuration.md)\n- [Authentication and credential scopes](../getting-started/authentication-and-credential-scopes.md)\n- [Errors and retry decisions](../../../reference/errors.md)\n",
    "text": "Dify models and knowledge metadata\n\nUse this family to discover configured workspace models, define dataset\nmetadata, enable built-in fields, or assign values to documents. All eight\noperations use one workspace-scoped knowledge credential.\n\nMetadata can expose document identity, upload history, source, and business\nattributes. Approval must bind each mutation to exact field identities,\ndocuments, replacement semantics, and readback evidence.\n\nChoose an operation\n\n| Operation suffix | Method and route | Purpose | Policy |\n\n| model.list | GET /v1/workspaces/current/models/model-types/{modeltype} | List configured models by type | Low-risk read; retry supported |\n| metadata.create | POST /v1/datasets/{datasetid}/metadata | Create one custom field | Medium mutation; approval and key required |\n| metadata.list | GET /v1/datasets/{datasetid}/metadata | List fields and usage counts | Low-risk read; retry supported |\n| metadata.update | PATCH /v1/datasets/{datasetid}/metadata/{metadataid} | Rename one custom field | Medium mutation; approval and key required |\n| metadata.delete | DELETE /v1/datasets/{datasetid}/metadata/{metadataid} | Delete a field and its values | High mutation; approval and key required |\n| metadata.builtin.list | GET /v1/datasets/{datasetid}/metadata/built-in | List built-in field definitions | Low-risk read; retry supported |\n| metadata.builtin.update | POST /v1/datasets/{datasetid}/metadata/built-in/{action} | Enable or disable built-ins | Medium mutation; approval and key required |\n| document.metadata.update | POST /v1/datasets/{datasetid}/documents/metadata | Update metadata for document entries | Medium mutation; approval and key required |\n\nThese Tool operations have knowledge scope and no app-mode projection. The\ncapability template is:\n\ncap:dify:knowledge::\n\nThe credential selects the workspace. Dataset and metadata route IDs must be\nprovider UUIDs inside that workspace.\n\nDiscover available models\n\nmodel.list accepts one of these modeltype values:\n• text-embedding\n• rerank\n• llm\n• tts\n• speech2text\n• moderation\n\n{\n  \"modeltype\": \"text-embedding\"\n}\n\nThe result contains data, grouped by provider. Provider entries expose\nidentity, localized labels, configuration status, and model records.\n\nUse the returned provider and model identifiers when configuring knowledge\nbases or indexing. Discovery proves visibility at read time, not future quota,\navailability, quality, or successful invocation.\n\nCreate and list custom fields\n\nmetadata.create requires body.type and body.name. Type accepts string,\nnumber, or time.\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000701\",\n  \"body\": {\n    \"type\": \"string\",\n    \"name\": \"policyregion\"\n  }\n}\n\nThe pinned service limits names to 255 characters. A name must be unique in\nthe dataset and cannot equal a built-in field name. Apply a caller policy that\nalso rejects blank or ambiguous names.\n\nCreation returns status 201 with id, type, and name. Persist the returned\nID because document binding uses field identity, not only its visible name.\n\nmetadata.list returns docmetadata and builtinfieldenabled. Each custom\nentry contains id, name, type, and the count of bound documents.\n\nRename or delete a custom field\n\nRename requires metadataid and a body name:\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000701\",\n  \"metadataid\": \"0190c42f-2d5a-7000-8000-000000000702\",\n  \"body\": {\n    \"name\": \"approvedregion\"\n  }\n}\n\nThe provider migrates the metadata key across bound documents and keeps its\nvalue. The new name follows the same length, uniqueness, and built-in-name\nrules.\n\nmetadata.delete removes the field, its bindings, and its values from related\ndocuments. Success returns empty status 204 and has no rollback contract.\n\nThe pinned rename and delete helpers catch internal exceptions. A nominal\nresponse can therefore be insufficient evidence of the intended state. Always\nread metadata.list and affected documents after either mutation.\n\nManage built-in fields\n\nmetadata.builtin.list returns five static definitions:\n\n| Name | Type |\n\n| documentname | string |\n| uploader | string |\n| uploaddate | time |\n| lastupdatedate | time |\n| source | string |\n\nThe definitions do not prove that built-in fields are enabled for the selected\ndataset. Read metadata.list for builtinfieldenabled.\n\nSet action to enable or disable:\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000701\",\n  \"action\": \"enable\",\n  \"body\": {}\n}\n\nEnable backfills those five values on working documents. Disable removes the\nkeys and marks the dataset setting false.\n\nThe pinned provider helper catches internal failures before returning\nresult: success. Confirm the flag and sample affected documents after either\naction.\n\nUpdate document metadata\n\ndocument.metadata.update accepts body.operationdata. Each entry names one\ndocument, its field values, and whether the change is partial.\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000701\",\n  \"body\": {\n    \"operationdata\": [\n      {\n        \"documentid\": \"0190c42f-2d5a-7000-8000-000000000703\",\n        \"metadatalist\": [\n          {\n            \"id\": \"0190c42f-2d5a-7000-8000-000000000702\",\n            \"name\": \"approvedregion\",\n            \"value\": \"emea\"\n          }\n        ],\n        \"partialupdate\": true\n      }\n    ]\n  }\n}\n\nUse the exact ID, name, and type from metadata.list. The provider uses the ID\nfor its binding and the name for the stored document key. Mismatched identities\ncan create misleading data.\n\nWith partialupdate: true, Dify preserves unspecified metadata and bindings.\nWith false, the default, it starts from an empty custom map and replaces the\ndocument's custom bindings with the supplied list.\n\nWhen built-ins are enabled, the provider restores their current values after\neither mode. A custom update cannot remove those five system fields.\n\nThe provider commits each document entry separately. A later failure can leave\nearlier entries changed. The operation is not an atomic transaction across the\nwhole array.\n\nApply a tenant-policy count bound because the provider schema declares no\nroute-specific maximum for operationdata. Read every intended document after\nthe call before reporting batch success.\n\nApply mutation governance\n\nAll five mutations require a non-blank Action idempotency key of at most 512\nbytes. AIP retains its tenant-scoped reservation for 24 hours and revalidates\nthe input hash on collision.\n\nThe key does not prove provider deduplication. These operations publish no\nautomatic retry, cross-document transaction, reconciliation, cancellation, or\ncompensation support.\n\nTreat model inventory, field definitions, document values, upload identities,\nsources, counts, and provider errors as confidential PII-bearing data. Redact\nthem from general logs.\n\nRecover safely\n\n| Observation | Decision |\n\n| Route ID, model type, or body is rejected before dispatch | Correct the bounded request without claiming a provider effect |\n| Model is absent from discovery | Repair workspace provider configuration before selecting it |\n| Create response is lost | List fields by exact name and type before another create |\n| Rename returns no trustworthy record | Read the field list and affected document keys |\n| Delete returns 204 | Confirm the field and values are absent before closing the action |\n| Built-in toggle returns success | Confirm the dataset flag and sample document values |\n| Multi-document update fails partway | Read every intended document and reconcile only through new approvals |\n| Field ID and name no longer match | Refresh metadata discovery before another document mutation |\n| Returned data crosses a workspace or dataset boundary | Stop traffic and treat the event as an isolation incident |\n\nPreserve the Action ID, digest, approval, idempotency key, credential, dataset,\nfield identities, document set, mode, and readback evidence needed to settle an\nambiguous outcome.\n\nRelated documentation\n• Dify capability index (README.md)\n• Dify knowledge documents and indexing (knowledge-documents-and-indexing.md)\n• Dify connector configuration (../reference/configuration.md)\n• Authentication and credential scopes (../getting-started/authentication-and-credential-scopes.md)\n• Errors and retry decisions (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "eb7162a623e26ab7b84b0261b9deb0a12f2ab253da5937c6f1d75e03ceb2239b"
  }
}