Dify Octri Demo
PATCH/datasets/{dataset_id}

Update a knowledge base

Updates a knowledge base by changing only the fields included in the request body. Use name, permission, indexing_technique, or the retrieval settings to adjust its configuration. When you provide retrieval_model, include search_method, reranking_enable, top_k, and score_threshold_enabled.

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

1 parameter · 11 body fields
dataset_idstringrequired
The UUID of the knowledge base to update.

Knowledge base fields to update. Only fields included in the request body are changed.

descriptionstringoptional
Description of the knowledge base.
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.
external_retrieval_modelobjectoptional
Retrieval settings for external knowledge bases.
indexing_techniquestringoptional
`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.
Allowed:high_qualityeconomy
namestringoptional
Name of the knowledge base.
partial_member_listarray<object>optional
List of team members with access when `permission` is `partial_members`.
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_members
retrieval_modelobjectoptional
Retrieval configuration. When provided, include `search_method`, `reranking_enable`, `top_k`, and `score_threshold_enabled`; it can also configure metadata filtering, reranking, a score threshold, and search weights.

4 status codes
200Returns the updated knowledge base object, including its configuration and details such as document count, embedding model, and access settings.
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 API access is disabled for the knowledge base, the subscription request rate limit has been reached, or the API key is not scoped to the knowledge base.

One documented failure

  • forbidden

    Dataset api access is not enabled.

    forbidden (api access)

404Returned when no knowledge base matches `dataset_id`.

One documented failure

  • not_found

    Dataset not found.

    not_found

Error handling

A 400 is returned when the specified embedding or reranking model is not configured or available. A 403 is returned when API access is disabled for the knowledge base, the subscription request rate limit is reached, or the API key does not have access to it. A 404 is returned when the dataset_id path parameter does not identify an existing knowledge base; name must be 1 to 40 characters, description must not exceed 400 characters, and retrieval_model must include search_method, reranking_enable, top_k, and score_threshold_enabled.