Dify Octri Demo
POST/datasets

Create an empty knowledge base

Creates an empty knowledge base for storing and retrieving documents. Supply name and configure options such as provider, indexing_technique, and retrieval_model; name must be 1 to 40 characters. Add documents afterward with the create-document-by-text or create-document-by-file operation.

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

11 body fields

Configuration for the new knowledge base. name is required; other fields configure its description, access, indexing, and retrieval.

descriptionstringoptional
Description of the knowledge base.
Default:
embedding_modelstringoptional
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_providerstringoptional
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`.
external_knowledge_api_idstringoptional
ID of the external knowledge API connection.
external_knowledge_idstringoptional
ID of the external knowledge base.
indexing_techniquestringoptional
`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.
Allowed:high_qualityeconomy
namestringrequired
Name of the knowledge base.
permissionstringoptional
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.
Allowed:only_meall_team_memberspartial_membersDefault:only_me
providerstringoptional
`vendor` for internal knowledge base, `external` for external knowledge base.
Allowed:vendorexternalDefault:vendor
retrieval_modelobjectoptional
Retrieval configuration. Includes required `search_method` (`keyword_search`, `semantic_search`, `full_text_search`, or `hybrid_search`), `reranking_enable`, `top_k`, and `score_threshold_enabled` fields; optional settings include metadata filtering conditions, reranking mode (`reranking_model` or `weighted_score`), reranking model configuration, score threshold, and hybrid-search weights.
summary_index_settingobjectoptional
Summary index configuration.

4 status codes
200Returns the created knowledge base object, including its identifier, name, description, indexing and embedding configuration, document count, access settings, and creation details.
app_countintegeroptional
Number of applications currently using this knowledge base.
author_namestringoptional
Display name of the creator.
built_in_field_enabledbooleanoptional
Whether built-in metadata fields (e.g., `document_name`, `uploader`) are enabled.
chunk_structurestringoptional
Chunk structure configuration.
created_atnumberoptional
Creation timestamp (Unix epoch in seconds).
created_bystringoptional
ID of the user who created the knowledge base.
data_source_typestringoptional
Data source type of the documents, `null` if not yet configured.
descriptionstringoptional
Optional text describing the purpose or contents of the knowledge base.
doc_formstringoptional
Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction.
doc_metadataarray<object>optional
Metadata field definitions for the knowledge base.
document_countintegeroptional
Total number of documents in the knowledge base.
embedding_availablebooleanoptional
Whether the configured embedding model is currently available.
embedding_modelstringoptional
Name of the embedding model used for indexing.
embedding_model_providerstringoptional
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_apibooleanoptional
Whether API access is enabled for this knowledge base.
external_knowledge_infoobjectoptional
Connection details for external knowledge bases. Present when `provider` is `external`.
external_retrieval_modelobjectoptional
Retrieval settings for external knowledge bases. `null` for internal knowledge bases.
icon_infoobjectoptional
Icon display configuration for the knowledge base.
idstringoptional
Unique identifier of the knowledge base.
indexing_techniquestringoptional
`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.
is_multimodalbooleanoptional
Whether multimodal content processing is enabled.
is_publishedbooleanoptional
Whether the knowledge base is published.
maintainerstringoptional
Display name of the knowledge base maintainer. `null` if not set.
namestringoptional
Display name of the knowledge base. Unique within the workspace.
partial_member_listarray<string>optional
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`.
permissionstringoptional
Controls who can access this knowledge base. Possible values: `only_me`, `all_team_members`, `partial_members`.
pipeline_idstringoptional
Pipeline ID, if a custom processing pipeline is configured.
providerstringoptional
Provider type. `vendor` for internally managed, `external` for external knowledge base connections.
retrieval_model_dictobjectoptional
Retrieval configuration for the knowledge base.
runtime_modestringoptional
Runtime processing mode.
summary_index_settingobjectoptional
Summary index configuration.
tagsarray<object>optional
Tags associated with this knowledge base.
total_available_documentsintegeroptional
Number of documents that are enabled and available.
total_documentsintegeroptional
Total number of documents.
updated_atnumberoptional
Last update timestamp (Unix epoch in seconds).
updated_bystringoptional
ID of the user who last updated the knowledge base.
word_countintegeroptional
Total word count across all documents.
400Returned when the specified embedding or reranking model is not configured or available.

One documented failure

  • invalid_param

    No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.

    invalid_param

403Returned when the subscription's knowledge base request rate limit has been reached, or when the API key is scoped to specific knowledge bases instead of all knowledge bases.

One documented failure

  • forbidden

    Sorry, you have reached the knowledge base request rate limit of your subscription.

    forbidden (rate limit)

409Returned when a knowledge base with the same name already exists.

One documented failure

  • dataset_name_duplicate

    The dataset name already exists. Please modify your dataset name.

    dataset_name_duplicate

Error handling

name is required and must be 1 to 40 characters; indexing_technique, permission, and provider must use their documented values when supplied. A 400 is returned when the specified embedding or reranking model is not configured or available. A 403 is returned when the subscription request rate limit is reached or the API key is restricted to specific knowledge bases; a 409 is returned if a knowledge base with the same name already exists.