Why do I get a 400 BAD REQUEST when specifying retrieval_model parameters in the request to create an empty knowledge base ?

[ZhegeMaw]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

I can successfully call the backend API to create an empty knowledge base, but I get a 400 error as soon as I add retrieval parameters. I've tried constructing the JSON myself and also used the example request from the official documentation, but both failed. Where exactly am I going wrong with the parameters I'm passing?

2. Additional context or comments

API: /datasets
Method: POST
1、The code I constructed myself

2、The JSON body constructed according to the official example.

The response：
Response{protocol=http/1.1, code=400, message=BAD REQUEST, url=http://192.168.251.xxx/v1/datasets}

[dosubot[bot]]

Hi @ZhegeMaw! I'm Dosu and I’m helping the dify team.

The 400 BAD REQUEST error happens when the retrieval_model parameters in your request don't match the expected schema or contain invalid values. The backend uses strict validation: every field in retrieval_model must be present and correctly typed, and nested objects like weights and reranking_model must include required fields. For example, weights must have a weight_type (allowed values: "semantic_first", "keyword_first", "customized"), and reranking_model must use valid provider/model names recognized by Dify—using an unsupported provider like "Qwen" will trigger a 400 error source.

Common causes include: malformed JSON, missing required fields (like weight_type in weights), incorrect enum values (search_method must be a valid option), or sending the request body as raw text instead of proper JSON source. Also, ensure your Content-Type header is set to application/json.

Here’s a minimal example of a valid retrieval_model object:

"retrieval_model": {
  "search_method": "hybrid_search",
  "reranking_enable": false,
  "reranking_model": {
    "reranking_provider_name": "",
    "reranking_model_name": ""
  },
  "reranking_mode": null,
  "top_k": 4,
  "score_threshold_enabled": false,
  "score_threshold": null,
  "weights": {
    "weight_type": "semantic_first"
  }
}

Double-check your JSON structure, required fields, and provider/model names. If you still get a 400 error, inspect the response body for a more specific message—sometimes it will say which field is invalid or missing source.

To reply, just mention @dosu.

---

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

   

[ZhegeMaw]

Thank you very much. After revising according to the minimal example you provided, I was able to make the request successfully. It seems the information in the API documentation might not be up-to-date, I made adjustments based on the request parameters from the web API . I’d like to confirm whether the request parameters for the web and backend API are consistent. If they are consistent, can I refer to the web API when calling other interfaces?
Additionally, here is my successful parameter configuration. Those who need it in the future can use this for reference:

{
    "name": "name",
    "description": "description",
    "permission": "all_team_members",
    "indexing_technique": "high_quality",
    "embedding_model": "bge-m3",
    "embedding_model_provider": "langgenius/gpustack/gpustack",
    "retrieval_model": {
        "search_method": "hybrid_search",
        "reranking_enable": false,
        "reranking_model": {
            "reranking_model_name": "",
            "reranking_provider_name": ""
        },
        "top_k": 2,
        "score_threshold_enabled": false,
        "score_threshold": null,
        "weights": {
            "weight_type": "customized",
            "vector_setting": {
                "vector_weight": 0.7,
                "embedding_provider_name": "",
                "embedding_model_name": ""
            },
            "keyword_setting": {
                "keyword_weight": 0.3
            }
        }
    }
}

[dosubot[bot]]

Yes, the request parameters used by the web frontend and the backend API for dataset creation (including retrieval_model) are consistent—they use the same schema and field names. The web app builds its requests using a RetrievalConfig object that matches the backend’s expected structure, so referencing the web API’s request parameters is a reliable way to construct backend API calls for this and similar endpoints. This approach is common practice, especially since the API documentation can lag behind the actual implementation or contain outdated examples.

Just be aware that some advanced options (like rerank models or custom weights) may depend on backend support and version, so if you use new features, check for any recent changes or release notes. For most use cases, using the web API as a reference will keep your requests compatible with the backend API requirements. If you run into 400 errors, double-check for required fields, valid enum values, and proper JSON formatting as the backend uses strict validation.

References:

• Web frontend and backend use the same schema for retrieval_model
• API request payload matches web frontend structure
• Docs and issues confirm web API parameters reflect backend requirements

To reply, just mention @dosu.

---

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