Knowledge Bases

Create an Empty Knowledge Base

Changed on

Creates an empty knowledge base. Add documents to it with Create Document by Text or Create Document by File.

post/datasets

Request

  • Base URL
    https://api.dify.ai/v1
  • URL
    https://api.dify.ai/v1/datasets
  • Auth
    HTTP bearer

Request body

descriptionstring

Description of the knowledge base.

embedding_modelstring

Embedding model name. Use the model field from Get Available Models with model_type=text-embedding.

embedding_model_providerstring

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 with model_type=text-embedding.

external_knowledge_api_idstring

ID of the external knowledge API connection.

external_knowledge_idstring

ID of the external knowledge base.

indexing_technique'high_quality' | 'economy' nullable

high_quality uses embedding models for precise search; economy uses keyword-based indexing.

namestring required

Name of the knowledge base.

permission'only_me' | 'all_team_members' | 'partial_members'

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'vendor' | 'external'

vendor for internal knowledge base, external for external knowledge base.

Response

Knowledge base created successfully.

app_countinteger

Number of applications currently using this knowledge base.

author_namestring

Display name of the creator.

built_in_field_enabledboolean

Whether built-in metadata fields (e.g., document_name, uploader) are enabled.

chunk_structurestring nullable

Chunk structure configuration.

created_atnumber

Creation timestamp (Unix epoch in seconds).

created_bystring

ID of the user who created the knowledge base.

data_source_typestring

Data source type of the documents, null if not yet configured.

descriptionstring

Optional text describing the purpose or contents of the knowledge base.

doc_formstring

Document chunking mode. text_model for standard text chunking, hierarchical_model for parent-child structure, qa_model for QA pair extraction.

document_countinteger

Total number of documents in the knowledge base.

embedding_availableboolean

Whether the configured embedding model is currently available.

embedding_modelstring

Name of the embedding model used for indexing.

embedding_model_providerstring

Embedding model provider identifier, formatted as organization/plugin_name/provider_name (e.g. langgenius/openai/openai). Legacy knowledge bases may return the bare short form (e.g. openai).

enable_apiboolean

Whether API access is enabled for this knowledge base.

idstring

Unique identifier of the knowledge base.

indexing_techniquestring

high_quality uses embedding models for precise search; economy uses keyword-based indexing.

is_multimodalboolean

Whether multimodal content processing is enabled.

is_publishedboolean

Whether the knowledge base is published.

maintainerstring nullable

Display name of the knowledge base maintainer. null if not set.

namestring

Display name of the knowledge base. Unique within the workspace.

partial_member_liststring[] nullable

Account IDs of members granted access when permission is partial_members. Always present on the update response; on the detail response, present only when permission is partial_members.

permissionstring

Controls who can access this knowledge base. Possible values: only_me, all_team_members, partial_members.

pipeline_idstring nullable

Pipeline ID, if a custom processing pipeline is configured.

providerstring

Provider type. vendor for internally managed, external for external knowledge base connections.

runtime_modestring nullable

Runtime processing mode.

total_available_documentsinteger

Number of documents that are enabled and available.

total_documentsinteger

Total number of documents.

updated_atnumber

Last update timestamp (Unix epoch in seconds).

updated_bystring

ID of the user who last updated the knowledge base.

word_countinteger

Total word count across all documents.

Changes