Dify Knowledge Bases API
Operations for managing knowledge bases, including creation, configuration, and retrieval. 6 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-datasets-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 Knowledge Bases 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: Knowledge Bases
description: Operations for managing knowledge bases, including creation, configuration, and retrieval.
paths:
/datasets:
post:
tags:
- Knowledge Bases
summary: Create an Empty Knowledge Base
description: Creates an empty knowledge base. Add documents to it with [Create Document by Text](/en/api-reference/documents/create-document-by-text)
or [Create Document by File](/en/api-reference/documents/create-document-by-file).
operationId: createDataset
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 40
description: Name of the knowledge base.
description:
type: string
maxLength: 400
default: ''
description: Description of the knowledge base.
indexing_technique:
type: string
enum:
- high_quality
- economy
nullable: true
description: '`high_quality` uses embedding models for precise search; `economy` uses
keyword-based indexing.'
permission:
type: string
enum:
- only_me
- all_team_members
- partial_members
default: only_me
description: Controls who can access this knowledge base. `only_me` restricts to the
creator, `all_team_members` grants access to the entire workspace, `partial_members`
grants access to specified members.
provider:
type: string
enum:
- vendor
- external
default: vendor
description: '`vendor` for internal knowledge base, `external` for external knowledge
base.'
embedding_model:
type: string
description: Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models)
with `model_type=text-embedding`.
embedding_model_provider:
type: string
description: 'Embedding model provider identifier, formatted as `organization/plugin_name/provider_name`
(e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius/<name>/<name>`
and works only for langgenius-published plugins.
Get valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models)
with `model_type=text-embedding`.'
retrieval_model:
$ref: '#/components/schemas/RetrievalModel'
description: Retrieval model configuration. Controls how chunks are searched and ranked
when querying this knowledge base.
external_knowledge_api_id:
type: string
description: ID of the external knowledge API connection.
external_knowledge_id:
type: string
description: ID of the external knowledge base.
summary_index_setting:
type: object
nullable: true
description: Summary index configuration.
properties:
enable:
type: boolean
description: Whether to enable summary indexing.
model_name:
type: string
description: Name of the model used for generating summaries.
model_provider_name:
type: string
description: Provider of the summary generation model.
summary_prompt:
type: string
description: Custom prompt template for summary generation.
responses:
'200':
description: Knowledge base created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
examples:
success:
summary: Response Example
value:
id: c42e2a6e-40b3-4330-96f8-f1e4d768e8c9
name: Product Documentation
description: Technical documentation for the product API
provider: vendor
permission: only_me
data_source_type: null
indexing_technique: high_quality
app_count: 0
document_count: 0
word_count: 0
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
author_name: admin
created_at: 1741267200
updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
updated_at: 1741267200
embedding_model: text-embedding-3-small
embedding_model_provider: langgenius/openai/openai
embedding_available: true
retrieval_model_dict:
search_method: semantic_search
reranking_enable: false
reranking_mode: null
reranking_model:
reranking_provider_name: ''
reranking_model_name: ''
weights: null
top_k: 3
score_threshold_enabled: false
score_threshold: null
tags: []
doc_form: text_model
external_knowledge_info: null
external_retrieval_model: null
doc_metadata: []
built_in_field_enabled: true
pipeline_id: null
runtime_mode: null
chunk_structure: null
icon_info: null
summary_index_setting: null
is_published: false
total_documents: 0
total_available_documents: 0
enable_api: true
is_multimodal: false
maintainer: admin
'400':
description: '`invalid_param` : The embedding or reranking model you specified is not configured
or available.'
content:
application/json:
examples:
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: No Embedding Model available. Please configure a valid provider in the Settings
-> Model Provider.
'403':
description: '`forbidden` : Your subscription''s knowledge base request rate limit has been
reached.'
content:
application/json:
examples:
forbidden:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'409':
description: '`dataset_name_duplicate` : A knowledge base with the same name already exists.'
content:
application/json:
examples:
dataset_name_duplicate:
summary: dataset_name_duplicate
value:
status: 409
code: dataset_name_duplicate
message: The dataset name already exists. Please modify your dataset name.
x-mint:
href: /en/api-reference/knowledge-bases/create-an-empty-knowledge-base
metadata:
title: Create an Empty Knowledge Base
sidebarTitle: Create an Empty Knowledge Base
get:
tags:
- Knowledge Bases
summary: List Knowledge Bases
description: Returns a paginated list of knowledge bases, optionally filtered by keyword or tags.
operationId: listDatasets
parameters:
- name: page
in: query
schema:
type: integer
default: 1
description: Page number.
- name: limit
in: query
schema:
type: integer
default: 20
description: Number of items per page.
- name: keyword
in: query
schema:
type: string
description: Search keyword to filter by name.
- name: include_all
in: query
schema:
type: boolean
default: false
description: Whether to include all knowledge bases regardless of permissions.
- name: tag_ids
in: query
schema:
type: array
items:
type: string
style: form
explode: true
description: Tag IDs to filter by. Get tag IDs from [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags).
responses:
'200':
description: List of knowledge bases.
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: Array of knowledge base objects.
items:
$ref: '#/components/schemas/Dataset'
has_more:
type: boolean
description: Whether more items exist on the next page.
limit:
type: integer
description: Number of items per page.
total:
type: integer
description: Total number of matching items.
page:
type: integer
description: Current page number.
examples:
success:
summary: Response Example
value:
data:
- id: c42e2a6e-40b3-4330-96f8-f1e4d768e8c9
name: Product Documentation
description: Technical documentation for the product API
provider: vendor
permission: only_me
data_source_type: null
indexing_technique: high_quality
app_count: 0
document_count: 0
word_count: 0
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
author_name: admin
created_at: 1741267200
updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
updated_at: 1741267200
embedding_model: text-embedding-3-small
embedding_model_provider: langgenius/openai/openai
embedding_available: true
retrieval_model_dict:
search_method: semantic_search
reranking_enable: false
reranking_mode: null
reranking_model:
reranking_provider_name: ''
reranking_model_name: ''
weights: null
top_k: 3
score_threshold_enabled: false
score_threshold: null
tags: []
doc_form: text_model
external_knowledge_info: null
external_retrieval_model: null
doc_metadata: []
built_in_field_enabled: true
pipeline_id: null
runtime_mode: null
chunk_structure: null
icon_info: null
summary_index_setting: null
is_published: false
total_documents: 0
total_available_documents: 0
enable_api: true
is_multimodal: false
maintainer: admin
has_more: false
limit: 20
total: 1
page: 1
x-mint:
href: /en/api-reference/knowledge-bases/list-knowledge-bases
metadata:
title: List Knowledge Bases
sidebarTitle: List Knowledge Bases
/datasets/{dataset_id}:
get:
tags:
- Knowledge Bases
summary: Get Knowledge Base
description: Returns detailed information about a knowledge base, including its embedding model,
retrieval configuration, and document statistics.
operationId: getDatasetDetail
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
responses:
'200':
description: Knowledge base details.
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
examples:
success:
summary: Response Example
value:
id: c42e2a6e-40b3-4330-96f8-f1e4d768e8c9
name: Product Documentation
description: Technical documentation for the product API
provider: vendor
permission: only_me
data_source_type: null
indexing_technique: high_quality
app_count: 0
document_count: 0
word_count: 0
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
author_name: admin
created_at: 1741267200
updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
updated_at: 1741267200
embedding_model: text-embedding-3-small
embedding_model_provider: langgenius/openai/openai
embedding_available: true
retrieval_model_dict:
search_method: semantic_search
reranking_enable: false
reranking_mode: null
reranking_model:
reranking_provider_name: ''
reranking_model_name: ''
weights: null
top_k: 3
score_threshold_enabled: false
score_threshold: null
tags: []
doc_form: text_model
external_knowledge_info: null
external_retrieval_model: null
doc_metadata: []
built_in_field_enabled: true
pipeline_id: null
runtime_mode: null
chunk_structure: null
icon_info: null
summary_index_setting: null
is_published: false
total_documents: 0
total_available_documents: 0
enable_api: true
is_multimodal: false
maintainer: admin
'403':
description: '`forbidden` : API access is not enabled for this knowledge base.'
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` : No knowledge base matches `dataset_id`.'
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/knowledge-bases/get-knowledge-base
metadata:
title: Get Knowledge Base
sidebarTitle: Get Knowledge Base
patch:
tags:
- Knowledge Bases
summary: Update Knowledge Base
description: Updates a knowledge base. Only the fields included in the request body are changed.
operationId: updateDataset
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 40
description: Name of the knowledge base.
description:
type: string
maxLength: 400
description: Description of the knowledge base.
indexing_technique:
type: string
enum:
- high_quality
- economy
nullable: true
description: '`high_quality` uses embedding models for precise search; `economy` uses
keyword-based indexing.'
permission:
type: string
enum:
- only_me
- all_team_members
- partial_members
description: Controls who can access this knowledge base. `only_me` restricts to the
creator, `all_team_members` grants access to the entire workspace, `partial_members`
grants access to specified members.
embedding_model:
type: string
description: Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models)
with `model_type=text-embedding`.
embedding_model_provider:
type: string
description: 'Embedding model provider identifier, formatted as `organization/plugin_name/provider_name`
(e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius/<name>/<name>`
and works only for langgenius-published plugins.
Get valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models)
with `model_type=text-embedding`.'
retrieval_model:
$ref: '#/components/schemas/RetrievalModel'
description: Retrieval model configuration. Controls how chunks are searched and ranked
when querying this knowledge base.
partial_member_list:
type: array
description: List of team members with access when `permission` is `partial_members`.
items:
type: object
properties:
user_id:
type: string
description: ID of the team member to grant access.
external_retrieval_model:
type: object
description: Retrieval settings for external knowledge bases.
properties:
top_k:
type: integer
description: Maximum number of results to return.
score_threshold:
type: number
description: Minimum similarity score threshold for filtering results.
score_threshold_enabled:
type: boolean
description: Whether score threshold filtering is enabled.
external_knowledge_id:
type: string
description: ID of the external knowledge base.
external_knowledge_api_id:
type: string
description: ID of the external knowledge API connection.
responses:
'200':
description: Knowledge base updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
examples:
success:
summary: Response Example
value:
id: c42e2a6e-40b3-4330-96f8-f1e4d768e8c9
name: Product Documentation
description: Technical documentation for the product API
provider: vendor
permission: only_me
data_source_type: null
indexing_technique: high_quality
app_count: 0
document_count: 0
word_count: 0
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
author_name: admin
created_at: 1741267200
updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
updated_at: 1741267200
embedding_model: text-embedding-3-small
embedding_model_provider: langgenius/openai/openai
embedding_available: true
retrieval_model_dict:
search_method: semantic_search
reranking_enable: false
reranking_mode: null
reranking_model:
reranking_provider_name: ''
reranking_model_name: ''
weights: null
top_k: 3
score_threshold_enabled: false
score_threshold: null
tags: []
doc_form: text_model
external_knowledge_info: null
external_retrieval_model: null
doc_metadata: []
built_in_field_enabled: true
pipeline_id: null
runtime_mode: null
chunk_structure: null
icon_info: null
summary_index_setting: null
is_published: false
total_documents: 0
total_available_documents: 0
enable_api: true
is_multimodal: false
maintainer: admin
partial_member_list: []
'400':
description: '`invalid_param` : The embedding or reranking model you specified is not configured
or available.'
content:
application/json:
examples:
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: No Embedding Model available. Please configure a valid provider in the Settings
-> Model Provider.
'403':
description: '- `forbidden` : API access is not enabled for this knowledge base.
- `forbidden` : Your subscription''s knowledge base request rate limit has been reached.'
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` : No knowledge base matches `dataset_id`.'
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/knowledge-bases/update-knowledge-base
metadata:
title: Update Knowledge Base
sidebarTitle: Update Knowledge Base
delete:
tags:
- Knowledge Bases
summary: Delete Knowledge Base
description: Permanently deletes a knowledge base and all of its documents.
operationId: deleteDataset
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
responses:
'204':
description: Knowledge base deleted successfully.
'403':
description: '- `forbidden` : API access is not enabled for this knowledge base.
- `forbidden` : Your subscription''s knowledge base request rate limit has been reached.'
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` : No knowledge base matches `dataset_id`.'
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/knowledge-bases/delete-knowledge-base
metadata:
title: Delete Knowledge Base
sidebarTitle: Delete Knowledge Base
/datasets/{dataset_id}/retrieve:
post:
tags:
- Knowledge Bases
summary: Retrieve Chunks from a Knowledge Base / Test Retrieval
description: Searches a knowledge base and returns the chunks most relevant to the query, for both
production retrieval and test retrieval.
operationId: retrieveSegments
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
type: string
maxLength: 250
description: Search query text.
retrieval_model:
$ref: '#/components/schemas/RetrievalModel'
description: Retrieval model configuration. Controls how chunks are searched and ranked
when querying this knowledge base.
attachment_ids:
type: array
items:
type: string
nullable: true
description: List of attachment IDs to include in the retrieval context.
external_retrieval_model:
type: object
description: Retrieval settings for external knowledge bases.
properties:
top_k:
type: integer
description: Maximum number of results to return.
score_threshold:
type: number
description: Minimum similarity score threshold for filtering results.
score_threshold_enabled:
type: boolean
description: Whether score threshold filtering is enabled.
responses:
'200':
description: Retrieval results.
content:
application/json:
schema:
type: object
properties:
query:
type: object
description: The original query object.
properties:
content:
type: string
description: The query text.
records:
type: array
description: List of matched retrieval records.
items:
type: object
properties:
segment:
type: object
description: Matched chunk from the knowledge base.
properties:
id:
type: string
description: Unique identifier of the chunk.
position:
type: integer
description: Position of the chunk within the document.
document_id:
type: string
description: ID of the document this chunk belongs to.
content:
type: string
description: Text content of the chunk.
sign_content:
type: string
description: Signed content hash for integrity verification.
answer:
type: string
description: Answer content, used in Q&A mode documents.
word_count:
type: integer
description: Word count of the chunk content.
tokens:
type: integer
description: Token count of the chunk content.
keywords:
type: array
description: Keywords associated with this chunk for keyword-based retrieval.
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dify/refs/heads/main/openapi/dify-datasets-api-openapi.yml