[DOCS]: Error in API reference for "Retrieve Chunks from a Knowledge Base / Test Retrieval"

[yangzq50]

Type of Documentation Change

Error/Typo fix

Documentation Page URL or Path

https://docs.dify.ai/api-reference/datasets/retrieve-chunks-from-a-knowledge-base-test-retrieval

Current Content

In the code block "Retrieve Chunks from a Knowledge Base / Test Retrieval", I see the following usage:

import requests

url = "https://api.dify.ai/v1/datasets/{dataset_id}/retrieve"

payload = {
    "query": "<string>",
    "retrieval_model": {
        "search_method": "hybrid_search",
        "reranking_enable": True,
        "reranking_mode": {
            "reranking_provider_name": "<string>",
            "reranking_model_name": "<string>"
        },
        "top_k": 123,
        "score_threshold_enabled": True,
        "score_threshold": 123,
        "weights": 123,
        "metadata_filtering_conditions": {
            "logical_operator": "and",
            "conditions": [
                {
                    "name": "<string>",
                    "comparison_operator": "<string>",
                    "value": "<string>"
                }
            ]
        }
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

The "reranking_mode" part is probably wrong.

The error also exists in:

dify-docs/en/api-reference/openapi_knowledge.json

Lines 1772 to 1784 in 47b663d

	"reranking_mode": {
	"type": "object",
	"description": "Configuration for the reranking model.",
	"properties": {
	"reranking_provider_name": {
	"type": "string",
	"description": "The provider of the rerank model."
	},
	"reranking_model_name": {
	"type": "string",
	"description": "The name of the rerank model."
	}
	},

Suggested Changes

I see another doc for 3.0.x, which can be used to access cloud.dify.ai service:

dify-docs/versions/3-0-x/en/user-guide/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api.mdx

Lines 578 to 602 in 47b663d

	#### Retrieve Chunks from a Knowledge Base
	Request example:
	```bash
	curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/retrieve' \
	--header 'Authorization: Bearer {api_key}'\
	--header 'Content-Type: application/json'\
	--data-raw '{
	"query": "test",
	"retrieval_model": {
	"search_method": "keyword_search",
	"reranking_enable": false,
	"reranking_mode": null,
	"reranking_model": {
	"reranking_provider_name": "",
	"reranking_model_name": ""
	},
	"weights": null,
	"top_k": 1,
	"score_threshold_enabled": false,
	"score_threshold": null
	}
	}'
	```

Reason for Change

According to Dify source code, "reranking_mode" value can choose from "reranking_model" and "weighted_score".

https://github.com/langgenius/dify/blob/d01f2f7436eaa636b5cf5bfaf66bb0dbcb880e4d/api/core/rag/rerank/rerank_type.py#L1-L6

from enum import StrEnum


class RerankMode(StrEnum):
    RERANKING_MODEL = "reranking_model"
    WEIGHTED_SCORE = "weighted_score"

Code of Conduct

• I agree to follow Dify's documentation contribution guidelines
• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report, otherwise it will be closed.
• 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）
• Please do not modify this template :) and fill in all the required fields.

[dosubot]

Hi @yangzq50! I'm Dosu and I’m helping the dify-docs team.

You're right—the documentation for the "reranking_mode" parameter is incorrect. The API expects "reranking_mode" to be a string with valid values "reranking_model" or "weighted_score", not an object with "reranking_provider_name" and "reranking_model_name" fields. The correct structure is supported by the codebase, where "reranking_mode" is defined as an enum with those two string options, and the reranking model details (provider and model name) are passed separately in a "reranking_model" object if needed (see code, retrieval logic).

The current docs and schema (for example, in openapi_knowledge.json) incorrectly show "reranking_mode" as an object. The correct usage is also reflected in the 3.0.x user guide, where "reranking_mode" is a string or null, and "reranking_model" is a separate object.

This error could cause confusion or failed API calls for users following the current example. The documentation and schema should be updated so "reranking_mode" is a string ("reranking_model" or "weighted_score"), and the reranking model details are provided in a separate "reranking_model" object if needed.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}