[DOCS]: API Documentation Mismatch #293

New Issue

2026-02-16T05:19:47-05:00

yindo commented

2026-02-16 05:19:47 -05:00

Originally created by @pop9s on GitHub (Dec 29, 2025).

Type of Documentation Change

Error/Typo fix

Documentation Page URL or Path

https://docs.dify.ai/api-reference

Current Content

1.Next Suggested Questions: (GET)/messages/{message_id}/suggested
2.Create an Empty Knowledge Base:(POST)/datasets
3.File Upload:(POST)/files/upload

Suggested Changes

1.Next Suggested Questions: (GET)/messages/{message_id}/suggested-question
2.Create an Empty Knowledge Base:(POST)/datasets/init
3.File Upload:(GET)/files/upload

Reason for Change

We encountered a critical issues with the Dify official API documentation during integration: Some recorded API endpoints have inconsistent HTTP methods and URL paths with actual usage. These issues cause confusion during development and affect integration efficiency. We hope to supplement and correct the documentation accordingly.

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.

Originally created by @pop9s on GitHub (Dec 29, 2025). ### Type of Documentation Change Error/Typo fix ### Documentation Page URL or Path https://docs.dify.ai/api-reference ### Current Content 1.Next Suggested Questions: (GET)/messages/{message_id}/suggested 2.Create an Empty Knowledge Base:(POST)/datasets 3.File Upload:(POST)/files/upload ### Suggested Changes 1.Next Suggested Questions: (GET)/messages/{message_id}/suggested-question 2.Create an Empty Knowledge Base:(POST)/datasets/init 3.File Upload:(GET)/files/upload ### Reason for Change We encountered a critical issues with the Dify official API documentation during integration: Some recorded API endpoints have inconsistent HTTP methods and URL paths with actual usage. These issues cause confusion during development and affect integration efficiency. We hope to supplement and correct the documentation accordingly. ### Code of Conduct - [x] I agree to follow Dify's documentation [contribution guidelines](https://github.com/langgenius/dify/blob/0277a37fcad5ad86aeb239485c27fffd5cd90043/CONTRIBUTING.md) - [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones. - [x] I confirm that I am using English to submit this report, otherwise it will be closed. - [x] 【中文用户 & Non English User】请使用英语提交，否则会被关闭：） - [x] Please do not modify this template :) and fill in all the required fields.

yindo added the documentation label 2026-02-16 05:19:47 -05:00

yindo closed this issue

2026-02-16 05:19:47 -05:00

yindo commented

2026-02-16 05:19:47 -05:00

@dosubot[bot] commented on GitHub (Dec 29, 2025):

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

The current API documentation for these endpoints is accurate according to the codebase and recent issues:

"Next Suggested Questions" is implemented as a GET request to /messages/{message_id}/suggested, not /suggested-question (source).
"Create an Empty Knowledge Base" uses POST /datasets, not /datasets/init (source).
"File Upload" is a POST to /files/upload, not a GET (source).

The suggested changes do not match the actual implementation and should not be adopted unless the API itself changes. If you need to verify endpoints in the future, checking the OpenAPI spec or the codebase is the most reliable method.

To reply, just mention @dosu.

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

@dosubot[bot] commented on GitHub (Dec 29, 2025):  Hi @pop9s! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the dify-docs team.  The current API documentation for these endpoints is accurate according to the codebase and recent issues: - "Next Suggested Questions" is implemented as a GET request to `/messages/{message_id}/suggested`, not `/suggested-question` ([source](https://github.com/langgenius/dify/blob/7a5d2728a11f065dcaaf7719b165d845fd13db4b/api/controllers/service_api/app/message.py#L190-L228)). - "Create an Empty Knowledge Base" uses POST `/datasets`, not `/datasets/init` ([source](https://github.com/langgenius/dify/blob/7a5d2728a11f065dcaaf7719b165d845fd13db4b/api/controllers/service_api/dataset/dataset.py#L102-L206)). - "File Upload" is a POST to `/files/upload`, not a GET ([source](https://github.com/langgenius/dify/blob/7a5d2728a11f065dcaaf7719b165d845fd13db4b/api/controllers/service_api/app/file.py#L21-L67)). The suggested changes do not match the actual implementation and should not be adopted unless the API itself changes. If you need to verify endpoints in the future, checking the OpenAPI spec or the codebase is the most reliable method.  *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/e7a8ac84-9f5a-4616-8ebd-d1ae5d804647?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/e7a8ac84-9f5a-4616-8ebd-d1ae5d804647?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/e7a8ac84-9f5a-4616-8ebd-d1ae5d804647?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/e7a8ac84-9f5a-4616-8ebd-d1ae5d804647?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/e7a8ac84-9f5a-4616-8ebd-d1ae5d804647?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/e7a8ac84-9f5a-4616-8ebd-d1ae5d804647?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/e7a8ac84-9f5a-4616-8ebd-d1ae5d804647?feedback_type=other)</sup> [![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=The%20current%20API%20documentation%20for%20these%20endpoints%20is%20accurate%20according%20to%20the%20codebase%20and%20recent%20issues%3A%0A%0A-%20%22Next%20Suggested%20Questions%22%20is%20implemented%20as%20a%20GET%20request%20to%20%60/messages/%7Bmessage_id%7D/suggested%60%2C%20not%20%60/suggested-question%60%C2%A0%28%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/7a5d2728a11f065dcaaf7719b165d845fd13db4b/api/controllers/service_api/app/message.py%23L190-L228%29%29.%0A-%20%22Create%20an%20Empty%20Knowledge%20Base%22%20uses%20POST%20%60/datasets%60%2C%20not%20%60/datasets/init%60%C2%A0%28%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/7a5d2728a11f065dcaaf7719b165d845fd13db4b/api/controllers/service_api/dataset/dataset.py%23L102-L206%29%29.%0A-%20%22File%20Upload%22%20is%20a%20POST%20to%20%60/files/upload%60%2C%20not%20a%20GET%C2%A0%28%5Bsource%5D%28https%3A//github.com/langgenius/dify/blob/7a5d2728a11f065dcaaf7719b165d845fd13db4b/api/controllers/service_api/app/file.py%23L21-L67%29%29.%0A%0AThe%20suggested%20changes%20do%20not%20match%20the%20actual%20implementation%20and%20should%20not%20be%20adopted%20unless%20the%20API%20itself%20changes.%20If%20you%20need%20to%20verify%20endpoints%20in%20the%20future%2C%20checking%20the%20OpenAPI%20spec%20or%20the%20codebase%20is%20the%20most%20reliable%20method.) [![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot) [![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify-docs/issues/648)

yindo commented

2026-02-16 05:19:47 -05:00

@RiskeyL commented on GitHub (Jan 7, 2026):

Hi @pop9s, just wanted to follow up on this – dosubot has analyzed the code and shared its findings above. Could you take a look and let us know if this addresses your concerns?

@RiskeyL commented on GitHub (Jan 7, 2026): Hi @pop9s, just wanted to follow up on this – dosubot has analyzed the code and shared its findings above. Could you take a look and let us know if this addresses your concerns?

yindo commented

2026-02-16 05:19:47 -05:00

@dosubot[bot] commented on GitHub (Jan 18, 2026):

Hi, @pop9s. I'm Dosu, and I'm helping the dify-docs team manage their backlog and am marking this issue as stale.

Issue Summary:

You reported discrepancies in the Dify API documentation about HTTP methods and URL paths.
I clarified that the documentation aligns with the actual codebase and provided endpoint details.
Maintainer RiskeyL asked if my explanation addressed your concerns.
There have been no further updates or responses from you since then.

Next Steps:

Please let us know if this issue is still relevant to the latest version of the dify-docs repository by commenting here.
If we do not hear back within 5 days, this issue will be automatically closed.

Thank you for your understanding and contribution!

@dosubot[bot] commented on GitHub (Jan 18, 2026): Hi, @pop9s. I'm [Dosu](https://dosu.dev), and I'm helping the dify-docs team manage their backlog and am marking this issue as stale. **Issue Summary:** - You reported discrepancies in the Dify API documentation about HTTP methods and URL paths. - I clarified that the documentation aligns with the actual codebase and provided endpoint details. - Maintainer RiskeyL asked if my explanation addressed your concerns. - There have been no further updates or responses from you since then. **Next Steps:** - Please let us know if this issue is still relevant to the latest version of the dify-docs repository by commenting here. - If we do not hear back within 5 days, this issue will be automatically closed. Thank you for your understanding and contribution!

yindo referenced this issue

2026-02-16 06:15:31 -05:00

[PR #293] [MERGED] fix: bold display #437

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: langgenius/dify-docs#293