Dify Metadata API
Operations for managing knowledge base metadata fields and document metadata values. 7 operation(s) from the Dify Service API.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/dify-metadata-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.0.1
info:
title: Dify Metadata API
description: REST API for Dify applications and knowledge bases. Application endpoints authenticate
with an app API key; knowledge endpoints authenticate with a dataset API key.
version: 1.0.0
servers:
- url: https://{api_base_url}
description: Base URL of the Dify Service API. For self-hosted deployments, replace it with your own
API base URL.
variables:
api_base_url:
default: api.dify.ai/v1
description: Host and path of the API base URL, without the `https://` prefix.
security:
- ApiKeyAuth: []
tags:
- name: Metadata
description: Operations for managing knowledge base metadata fields and document metadata values.
paths:
/datasets/{dataset_id}/metadata:
post:
tags:
- Metadata
summary: Create Metadata Field
description: Create a custom metadata field for annotating documents in the knowledge base with
structured information.
operationId: createMetadataField
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- type
- name
properties:
type:
type: string
enum:
- string
- number
- time
description: '`string` for text values, `number` for numeric values, `time` for date/time
values.'
name:
type: string
description: Name for the metadata field. Must be unique among the knowledge base's
fields and at most 255 characters.
responses:
'201':
description: Metadata field created successfully.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Metadata field identifier.
name:
type: string
description: Metadata field name.
type:
type: string
description: Metadata field type.
examples:
success:
summary: Response Example
value:
id: b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e
name: author
type: string
'400':
description: '`invalid_param` : The metadata name already exists, exceeds 255 characters, or
conflicts with a built-in field.'
content:
application/json:
examples:
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: Metadata name already exists.
'403':
description: '- `forbidden` : Dataset api access is not enabled.
- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'404':
description: '`not_found` : Dataset not found.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
x-mint:
href: /en/api-reference/metadata/create-metadata-field
metadata:
title: Create Metadata Field
sidebarTitle: Create Metadata Field
get:
tags:
- Metadata
summary: List Metadata Fields
description: Returns all metadata fields for the knowledge base, both custom and built-in, with
the count of documents using each field.
operationId: listMetadataFields
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
responses:
'200':
description: Metadata fields for the knowledge base.
content:
application/json:
schema:
type: object
properties:
doc_metadata:
type: array
description: List of metadata field definitions.
items:
type: object
properties:
id:
type: string
description: Metadata field identifier.
name:
type: string
description: Metadata field name.
type:
type: string
description: Metadata field type.
count:
type: integer
description: Number of documents using this metadata field.
built_in_field_enabled:
type: boolean
description: Whether built-in metadata fields are enabled for this knowledge base.
examples:
success:
summary: Response Example
value:
doc_metadata:
- id: b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e
name: author
type: string
count: 3
built_in_field_enabled: true
'403':
description: '`forbidden` : Dataset api access is not enabled.'
content:
application/json:
examples:
forbidden:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
'404':
description: '`not_found` : Dataset not found.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
x-mint:
href: /en/api-reference/metadata/list-metadata-fields
metadata:
title: List Metadata Fields
sidebarTitle: List Metadata Fields
/datasets/{dataset_id}/metadata/{metadata_id}:
patch:
tags:
- Metadata
summary: Update Metadata Field
description: Rename a custom metadata field.
operationId: updateMetadataField
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: metadata_id
in: path
required: true
schema:
type: string
format: uuid
description: ID of the metadata field to rename. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: New name for the field. Must be unique among the knowledge base's fields
and at most 255 characters.
responses:
'200':
description: Metadata field updated successfully.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Metadata field identifier.
name:
type: string
description: Metadata field name.
type:
type: string
description: Metadata field type.
examples:
success:
summary: Response Example
value:
id: b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e
name: author
type: string
'400':
description: '`invalid_param` : The metadata name already exists, exceeds 255 characters, or
conflicts with a built-in field.'
content:
application/json:
examples:
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: Metadata name already exists.
'403':
description: '- `forbidden` : Dataset api access is not enabled.
- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'404':
description: '`not_found` : Dataset not found.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
x-mint:
href: /en/api-reference/metadata/update-metadata-field
metadata:
title: Update Metadata Field
sidebarTitle: Update Metadata Field
delete:
tags:
- Metadata
summary: Delete Metadata Field
description: Permanently delete a custom metadata field. Documents that used the field lose their
values for it.
operationId: deleteMetadataField
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: metadata_id
in: path
required: true
schema:
type: string
format: uuid
description: ID of the metadata field to delete. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields).
responses:
'204':
description: Success.
'403':
description: '- `forbidden` : Dataset api access is not enabled.
- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'404':
description: '`not_found` : Dataset not found.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
x-mint:
href: /en/api-reference/metadata/delete-metadata-field
metadata:
title: Delete Metadata Field
sidebarTitle: Delete Metadata Field
/datasets/{dataset_id}/metadata/built-in:
get:
tags:
- Metadata
summary: Get Built-in Metadata Fields
description: Returns the built-in metadata fields provided by the system.
operationId: getBuiltInMetadataFields
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
responses:
'200':
description: Built-in metadata fields.
content:
application/json:
schema:
type: object
properties:
fields:
type: array
description: List of system-provided metadata fields.
items:
type: object
properties:
name:
type: string
description: Built-in field identifier. `document_name` for the document title,
`uploader` for the creator, `upload_date` for creation time, `last_update_date`
for last modification time, `source` for the document origin.
type:
type: string
description: Field data type. `string` for text values, `time` for date/time
values.
examples:
success:
summary: Response Example
value:
fields:
- name: document_name
type: string
- name: uploader
type: string
- name: upload_date
type: time
- name: last_update_date
type: time
- name: source
type: string
'403':
description: '`forbidden` : Dataset api access is not enabled.'
content:
application/json:
examples:
forbidden:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
'404':
description: '`not_found` : Dataset not found.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
x-mint:
href: /en/api-reference/metadata/get-built-in-metadata-fields
metadata:
title: Get Built-in Metadata Fields
sidebarTitle: Get Built-in Metadata Fields
/datasets/{dataset_id}/metadata/built-in/{action}:
post:
tags:
- Metadata
summary: Update Built-in Metadata Field
description: Enable or disable built-in metadata fields for the knowledge base.
operationId: toggleBuiltInMetadataField
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: action
in: path
required: true
schema:
type: string
enum:
- enable
- disable
description: '`enable` to activate built-in metadata fields, `disable` to deactivate them.'
responses:
'200':
description: Built-in metadata field toggled successfully.
content:
application/json:
schema:
type: object
properties:
result:
type: string
description: Operation result.
examples:
success:
summary: Response Example
value:
result: success
'403':
description: '- `forbidden` : Dataset api access is not enabled.
- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'404':
description: '`not_found` : Dataset not found.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
x-mint:
href: /en/api-reference/metadata/update-built-in-metadata-field
metadata:
title: Update Built-in Metadata Field
sidebarTitle: Update Built-in Metadata Field
/datasets/{dataset_id}/documents/metadata:
post:
tags:
- Metadata
summary: Update Document Metadata in Batch
description: Update metadata values for multiple documents in a single request.
operationId: batchUpdateDocumentMetadata
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- operation_data
properties:
operation_data:
type: array
items:
type: object
required:
- document_id
- metadata_list
properties:
document_id:
type: string
description: ID of the document to update. See [List Documents](/en/api-reference/documents/list-documents).
metadata_list:
type: array
items:
type: object
required:
- id
- name
properties:
id:
type: string
description: Metadata field ID. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields).
name:
type: string
description: Metadata field name.
value:
description: Metadata value. Can be a string, number, or `null`.
description: Metadata fields to set on the document.
partial_update:
type: boolean
default: false
description: Whether to partially update metadata, keeping existing values for
unspecified fields.
description: Document metadata update operations, one entry per document.
responses:
'200':
description: Document metadata updated successfully.
content:
application/json:
schema:
type: object
properties:
result:
type: string
description: Operation result.
examples:
success:
summary: Response Example
value:
result: success
'400':
description: '`invalid_param` : Another metadata operation is already running for a document
in this request.'
content:
application/json:
examples:
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: Another document metadata operation is running, please wait a moment.
'403':
description: '- `forbidden` : Dataset api access is not enabled.
- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'404':
description: '- `not_found` : Knowledge base not found.
- `not_found` : A document referenced in `operation_data` does not exist in this knowledge
base.
- `not_found` : A metadata field referenced in `metadata_list` does not exist in this knowledge
base.'
content:
application/json:
examples:
not_found_1:
summary: not_found (knowledge base)
value:
status: 404
code: not_found
message: Dataset not found.
not_found_2:
summary: not_found (document)
value:
status: 404
code: not_found
message: Document not found.
not_found_3:
summary: not_found (metadata)
value:
status: 404
code: not_found
message: Metadata not found.
x-mint:
href: /en/api-reference/metadata/update-document-metadata-in-batch
metadata:
title: Update Document Metadata in Batch
sidebarTitle: Update Document Metadata in Batch
components:
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: API_KEY
description: '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](/en/api-reference/guides/get-started)).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key
fail with HTTP `401` (`unauthorized`).'
x-provenance:
generated: '2026-09-06'
method: derived
source: openapi/_original/dify-service-api-openapi.json
note: Per-tag split of the first-party Dify Service API OpenAPI harvested from https://docs.dify.ai/en/api-reference/openapi_service.json
(advertised in https://docs.dify.ai/llms.txt). Paths, schemas and operationIds are verbatim from that
spec.