Create an Empty Knowledge Base

post/datasets

Request example

curl --request POST \
  --url https://api.dify.ai/v1/datasets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "",
  "embedding_model": "<string>",
  "embedding_model_provider": "<string>",
  "external_knowledge_api_id": "<string>",
  "external_knowledge_id": "<string>",
  "indexing_technique": "high_quality",
  "name": "<string>",
  "permission": "only_me",
  "provider": "vendor",
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  },
  "summary_index_setting": {
    "enable": true,
    "model_name": "<string>",
    "model_provider_name": "<string>",
    "summary_prompt": "<string>"
  }
}'

import requests

url = "https://api.dify.ai/v1/datasets"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "description": "",
    "embedding_model": "<string>",
    "embedding_model_provider": "<string>",
    "external_knowledge_api_id": "<string>",
    "external_knowledge_id": "<string>",
    "indexing_technique": "high_quality",
    "name": "<string>",
    "permission": "only_me",
    "provider": "vendor",
    "retrieval_model": {
        "metadata_filtering_conditions": {
            "conditions": [
                {
                    "comparison_operator": "contains",
                    "name": "<string>",
                    "value": "<string>"
                }
            ],
            "logical_operator": "and"
        },
        "reranking_enable": True,
        "reranking_mode": "reranking_model",
        "reranking_model": {
            "reranking_model_name": "<string>",
            "reranking_provider_name": "<string>"
        },
        "score_threshold": 1,
        "score_threshold_enabled": True,
        "search_method": "keyword_search",
        "top_k": 1,
        "weights": {
            "keyword_setting": {
                "keyword_weight": 1
            },
            "vector_setting": {
                "embedding_model_name": "<string>",
                "embedding_provider_name": "<string>",
                "vector_weight": 1
            },
            "weight_type": "semantic_first"
        }
    },
    "summary_index_setting": {
        "enable": True,
        "model_name": "<string>",
        "model_provider_name": "<string>",
        "summary_prompt": "<string>"
    }
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/datasets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "description": "",
    "embedding_model": "<string>",
    "embedding_model_provider": "<string>",
    "external_knowledge_api_id": "<string>",
    "external_knowledge_id": "<string>",
    "indexing_technique": "high_quality",
    "name": "<string>",
    "permission": "only_me",
    "provider": "vendor",
    "retrieval_model": {
      "metadata_filtering_conditions": {
        "conditions": [
          {
            "comparison_operator": "contains",
            "name": "<string>",
            "value": "<string>"
          }
        ],
        "logical_operator": "and"
      },
      "reranking_enable": true,
      "reranking_mode": "reranking_model",
      "reranking_model": {
        "reranking_model_name": "<string>",
        "reranking_provider_name": "<string>"
      },
      "score_threshold": 1,
      "score_threshold_enabled": true,
      "search_method": "keyword_search",
      "top_k": 1,
      "weights": {
        "keyword_setting": {
          "keyword_weight": 1
        },
        "vector_setting": {
          "embedding_model_name": "<string>",
          "embedding_provider_name": "<string>",
          "vector_weight": 1
        },
        "weight_type": "semantic_first"
      }
    },
    "summary_index_setting": {
      "enable": true,
      "model_name": "<string>",
      "model_provider_name": "<string>",
      "summary_prompt": "<string>"
    }
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/datasets',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "description": "",
  "embedding_model": "<string>",
  "embedding_model_provider": "<string>",
  "external_knowledge_api_id": "<string>",
  "external_knowledge_id": "<string>",
  "indexing_technique": "high_quality",
  "name": "<string>",
  "permission": "only_me",
  "provider": "vendor",
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  },
  "summary_index_setting": {
    "enable": true,
    "model_name": "<string>",
    "model_provider_name": "<string>",
    "summary_prompt": "<string>"
  }
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/datasets"
	payload := strings.NewReader("{\n  \"description\": \"\",\n  \"embedding_model\": \"<string>\",\n  \"embedding_model_provider\": \"<string>\",\n  \"external_knowledge_api_id\": \"<string>\",\n  \"external_knowledge_id\": \"<string>\",\n  \"indexing_technique\": \"high_quality\",\n  \"name\": \"<string>\",\n  \"permission\": \"only_me\",\n  \"provider\": \"vendor\",\n  \"retrieval_model\": {\n    \"metadata_filtering_conditions\": {\n      \"conditions\": [\n        {\n          \"comparison_operator\": \"contains\",\n          \"name\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"logical_operator\": \"and\"\n    },\n    \"reranking_enable\": true,\n    \"reranking_mode\": \"reranking_model\",\n    \"reranking_model\": {\n      \"reranking_model_name\": \"<string>\",\n      \"reranking_provider_name\": \"<string>\"\n    },\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"search_method\": \"keyword_search\",\n    \"top_k\": 1,\n    \"weights\": {\n      \"keyword_setting\": {\n        \"keyword_weight\": 1\n      },\n      \"vector_setting\": {\n        \"embedding_model_name\": \"<string>\",\n        \"embedding_provider_name\": \"<string>\",\n        \"vector_weight\": 1\n      },\n      \"weight_type\": \"semantic_first\"\n    }\n  },\n  \"summary_index_setting\": {\n    \"enable\": true,\n    \"model_name\": \"<string>\",\n    \"model_provider_name\": \"<string>\",\n    \"summary_prompt\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/datasets"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"description\": \"\",\n  \"embedding_model\": \"<string>\",\n  \"embedding_model_provider\": \"<string>\",\n  \"external_knowledge_api_id\": \"<string>\",\n  \"external_knowledge_id\": \"<string>\",\n  \"indexing_technique\": \"high_quality\",\n  \"name\": \"<string>\",\n  \"permission\": \"only_me\",\n  \"provider\": \"vendor\",\n  \"retrieval_model\": {\n    \"metadata_filtering_conditions\": {\n      \"conditions\": [\n        {\n          \"comparison_operator\": \"contains\",\n          \"name\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"logical_operator\": \"and\"\n    },\n    \"reranking_enable\": true,\n    \"reranking_mode\": \"reranking_model\",\n    \"reranking_model\": {\n      \"reranking_model_name\": \"<string>\",\n      \"reranking_provider_name\": \"<string>\"\n    },\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"search_method\": \"keyword_search\",\n    \"top_k\": 1,\n    \"weights\": {\n      \"keyword_setting\": {\n        \"keyword_weight\": 1\n      },\n      \"vector_setting\": {\n        \"embedding_model_name\": \"<string>\",\n        \"embedding_provider_name\": \"<string>\",\n        \"vector_weight\": 1\n      },\n      \"weight_type\": \"semantic_first\"\n    }\n  },\n  \"summary_index_setting\": {\n    \"enable\": true,\n    \"model_name\": \"<string>\",\n    \"model_provider_name\": \"<string>\",\n    \"summary_prompt\": \"<string>\"\n  }\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/datasets')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "description": "",
  "embedding_model": "<string>",
  "embedding_model_provider": "<string>",
  "external_knowledge_api_id": "<string>",
  "external_knowledge_id": "<string>",
  "indexing_technique": "high_quality",
  "name": "<string>",
  "permission": "only_me",
  "provider": "vendor",
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  },
  "summary_index_setting": {
    "enable": true,
    "model_name": "<string>",
    "model_provider_name": "<string>",
    "summary_prompt": "<string>"
  }
}'

response = http.request(request)
puts response.read_body

Response

{
  "app_count": 0,
  "author_name": "admin",
  "built_in_field_enabled": true,
  "chunk_structure": null,
  "created_at": 1741267200,
  "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
  "data_source_type": null,
  "description": "Technical documentation for the product API",
  "doc_form": "text_model",
  "doc_metadata": [],
  "document_count": 0,
  "embedding_available": true,
  "embedding_model": "text-embedding-3-small",
  "embedding_model_provider": "langgenius/openai/openai",
  "enable_api": true,
  "external_knowledge_info": null,
  "external_retrieval_model": null,
  "icon_info": null,
  "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
  "indexing_technique": "high_quality",
  "is_multimodal": false,
  "is_published": false,
  "maintainer": "admin",
  "name": "Product Documentation",
  "permission": "only_me",
  "pipeline_id": null,
  "provider": "vendor",
  "retrieval_model_dict": {
    "reranking_enable": false,
    "reranking_mode": null,
    "reranking_model": {
      "reranking_model_name": "",
      "reranking_provider_name": ""
    },
    "score_threshold": null,
    "score_threshold_enabled": false,
    "search_method": "semantic_search",
    "top_k": 3,
    "weights": null
  },
  "runtime_mode": null,
  "summary_index_setting": null,
  "tags": [],
  "total_available_documents": 0,
  "total_documents": 0,
  "updated_at": 1741267200,
  "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
  "word_count": 0
}

{
  "code": "invalid_param",
  "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.",
  "status": 400
}

{
  "code": "forbidden",
  "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
  "status": 403
}

{
  "code": "forbidden",
  "message": "The API key is not authorized to access this knowledge base.",
  "status": 403
}

{
  "code": "dataset_name_duplicate",
  "message": "The dataset name already exists. Please modify your dataset name.",
  "status": 409
}

post/datasets

Authorization

Authorizationstringheaderrequired#

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).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Body

application/json

descriptionstring#

Description of the knowledge base.

Default: ""

Length: max 400

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_techniqueenum<string>#

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

Options:high_qualityeconomy

namestringrequired#

Name of the knowledge base.

Length: 1–40

permissionenum<string>#

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.

Default: "only_me"

Options:only_meall_team_memberspartial_members

providerenum<string>#

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

Default: "vendor"

Options:vendorexternal

retrieval_modelobject#

Show child attributes

metadata_filtering_conditionsobject#

Restrict retrieval to chunks whose document metadata matches the given conditions. Conditions are evaluated server-side against document metadata fields.

Show child attributes

conditionsobject[]#

List of metadata conditions to evaluate.

Show child attributes

comparison_operatorenum<string>required#

Comparison to apply, by metadata type:

String or array metadata: contains, not contains, start with, end with, is, is not, empty, not empty, in, not in
Numeric metadata: =, ≠, >, <, ≥, ≤
Time metadata: before, after

Options:containsnot containsstart withend withisis notemptynot emptyinnot in=≠><≥≤beforeafter

namestringrequired#

Metadata field name to compare against.

valuestring · string[] · number#

Value to compare against. Type depends on comparison_operator: string for most string operators, array of strings for in and not in, number for numeric operators, and omitted for empty and not empty.

logical_operatorenum<string>#

How to combine multiple conditions.

Default: "and"

Options:andor

reranking_enablebooleanrequired#

Whether reranking is enabled.

reranking_modeenum<string>#

Reranking mode. Required when reranking_enable is true.

Options:reranking_modelweighted_score

reranking_modelobject#

Reranking model configuration.

Show child attributes

reranking_model_namestring#

Name of the reranking model.

reranking_provider_namestring#

Reranking model provider identifier, formatted as organization/plugin_name/provider_name (e.g. langgenius/cohere/cohere). A bare name like cohere 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=rerank.

score_thresholdnumber#

Minimum similarity score for results. Only effective when score_threshold_enabled is true.

score_threshold_enabledbooleanrequired#

Whether score threshold filtering is enabled.

search_methodenum<string>required#

Search method used for retrieval.

Options:keyword_searchsemantic_searchfull_text_searchhybrid_search

top_kintegerrequired#

Maximum number of results to return.

weightsobject#

Weight configuration for hybrid search.

Show child attributes

keyword_settingobject#

Keyword search weight settings.

Show child attributes

keyword_weightnumber#

Weight assigned to keyword search results.

vector_settingobject#

Semantic search weight settings.

Show child attributes

embedding_model_namestring#

Name of the embedding model used for vector search.

embedding_provider_namestring#

Provider of the embedding model used for vector search.

vector_weightnumber#

Weight assigned to semantic (vector) search results.

weight_typeenum<string>#

Strategy for balancing semantic and keyword search weights.

Options:semantic_firstkeyword_firstcustomized

summary_index_settingobject#

Summary index configuration.

Show child attributes

enableboolean#

Whether to enable summary indexing.

model_namestring#

Name of the model used for generating summaries.

model_provider_namestring#

Provider of the summary generation model.

summary_promptstring#

Custom prompt template for summary generation.

Responses

application/json

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#

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.

doc_metadataobject[]#

Metadata field definitions for the knowledge base.

Show child attributes

idstring#

Metadata field identifier.

namestring#

Metadata field name.

typestring#

Metadata field value type.

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.

external_knowledge_infoobject#

Connection details for external knowledge bases. Present when provider is external.

Show child attributes

external_knowledge_api_endpointstring#

Endpoint URL of the external knowledge API.

external_knowledge_api_idstring#

ID of the external knowledge API connection.

external_knowledge_api_namestring#

Display name of the external knowledge API.

external_knowledge_idstring#

ID of the external knowledge base.

external_retrieval_modelobject#

Retrieval settings for external knowledge bases. null for internal knowledge bases.

Show child attributes

score_thresholdnumber#

Minimum similarity score threshold.

score_threshold_enabledboolean#

Whether score threshold filtering is enabled.

top_kinteger#

Maximum number of results to return from the external knowledge base.

icon_infoobject#

Icon display configuration for the knowledge base.

Show child attributes

iconstring#

Icon identifier or emoji.

icon_backgroundstring#

Background color for the icon.

icon_typestring#

Type of icon.

icon_urlstring#

URL of a custom icon image.

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#

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[]#

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#

Pipeline ID, if a custom processing pipeline is configured.

providerstring#

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

retrieval_model_dictobject#

Retrieval configuration for the knowledge base.

Show child attributes

reranking_enableboolean#

Whether reranking is enabled.

reranking_modestring#

Reranking mode. reranking_model for model-based reranking, weighted_score for score-based weighting. null if reranking is disabled.

reranking_modelobject#

Reranking model configuration.

Show child attributes

reranking_model_namestring#

Name of the reranking model.

reranking_provider_namestring#

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

score_thresholdnumber#

Minimum similarity score for results. Only effective when score_threshold_enabled is true.

score_threshold_enabledboolean#

Whether score threshold filtering is enabled.

search_methodstring#

Search method used for retrieval. keyword_search for keyword matching, semantic_search for embedding-based similarity, full_text_search for full-text indexing, hybrid_search for a combination of semantic and keyword approaches.

top_kinteger#

Maximum number of results to return.

weightsobject#

Weight configuration for hybrid search.

Show child attributes

keyword_settingobject#

Keyword search weight settings.

Show child attributes

keyword_weightnumber#

Weight assigned to keyword search results.

vector_settingobject#

Semantic search weight settings.

Show child attributes

embedding_model_namestring#

Name of the embedding model used for vector search.

embedding_provider_namestring#

Provider of the embedding model used for vector search.

vector_weightnumber#

Weight assigned to semantic (vector) search results.

weight_typestring#

Strategy for balancing semantic and keyword search weights.

runtime_modestring#

Runtime processing mode.

summary_index_settingobject#

Summary index configuration.

Show child attributes

enableboolean#

Whether summary indexing is enabled.

model_namestring#

Name of the model used for generating summaries.

model_provider_namestring#

Provider of the summary generation model.

summary_promptstring#

Prompt template used for summary generation.

tagsobject[]#

Tags associated with this knowledge base.

Show child attributes

idstring#

Tag identifier.

namestring#

Tag name.

typestring#

Tag type. Always knowledge for knowledge base tags.

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.

Submit Human Input Form List Knowledge Bases