Dify Octri Demo
POST/datasets/{dataset_id}/metadata

Create Metadata Field

Create a custom metadata field for annotating documents in the knowledge base with structured information.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 2 body fields
dataset_idstringrequired
Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).
namestringrequired
Name for the metadata field. Must be unique among the knowledge base's fields and at most 255 characters.
typestringrequired
`string` for text values, `number` for numeric values, `time` for date/time values.
Allowed:stringnumbertime

4 status codes
201Metadata field created successfully.
idstringoptional
Metadata field identifier.
namestringoptional
Metadata field name.
typestringoptional
Metadata field type.
400`invalid_param` : The metadata name already exists, exceeds 255 characters, or conflicts with a built-in field.

One documented failure

  • invalid_param

    Metadata name already exists.

    invalid_param

403- `forbidden` : Dataset api access is not enabled. - `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription. - `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them.

One documented failure

  • forbidden

    Dataset api access is not enabled.

    forbidden (api access)

404`not_found` : Dataset not found.

One documented failure

  • not_found

    Dataset not found.

    not_found

Error handling

A 400 is returned: invalid_param : The metadata name already exists, exceeds 255 characters, or conflicts with a built-in field. A 403 is returned: - forbidden : Dataset api access is not enabled.

  • forbidden : Sorry, you have reached the knowledge base request rate limit of your subscription.
  • forbidden : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them. A 404 is returned: not_found : Dataset not found.