Add backward compat APIs (#14427)

### What problem does this PR solve? Add backward compat APIs: ### Type of change - [x] Bug Fix (non-breaking change which fixes an issue)
2026-07-14 08:58:27 +08:00 · 2026-04-29 15:15:49 +08:00
parent c08ced09a7
commit b684c89950
7 changed files with 475 additions and 13 deletions
--- a/docs/references/http_api_reference.md
+++ b/docs/references/http_api_reference.md
@@ -37,6 +37,10 @@ A complete reference for RAGFlow's RESTful API. Before proceeding, please ensure

 Creates a model response for a given chat conversation.

+:::caution DEPRECATED
+The previous endpoint `POST /api/v1/chats_openai/{chat_id}/chat/completions` is deprecated. Please use this endpoint instead.
+:::
+
 This API follows the same request and response format as OpenAI's API. It allows you to interact with the model in a manner similar to how you would with [OpenAI's API](https://platform.openai.com/docs/api-reference/chat/create).

 #### Request
@@ -2369,6 +2373,10 @@ Failure:

 Updates content or configurations for a specified chunk.

+:::caution DEPRECATED
+The previous endpoint `PUT /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}` is deprecated. Please use this endpoint instead.
+:::
+
 #### Request

 - Method: PATCH
@@ -2908,11 +2916,11 @@ curl --request POST \
  - `"temperature"`: `float`
    Controls the randomness of the model's predictions. A lower temperature results in more conservative responses, while a higher temperature yields more creative and diverse responses. Defaults to `0.1`.
  - `"top_p"`: `float`
-    Also known as “nucleus sampling”, this parameter sets a threshold to select a smaller set of words to sample from. It focuses on the most likely words, cutting off the less probable ones. Defaults to `0.3`
+    Also known as "nucleus sampling", this parameter sets a threshold to select a smaller set of words to sample from. It focuses on the most likely words, cutting off the less probable ones. Defaults to `0.3`
  - `"presence_penalty"`: `float`
    This discourages the model from repeating the same information by penalizing words that have already appeared in the conversation. Defaults to `0.4`.
  - `"frequency penalty"`: `float`
-    Similar to the presence penalty, this reduces the model’s tendency to repeat the same words frequently. Defaults to `0.7`.
+    Similar to the presence penalty, this reduces the model's tendency to repeat the same words frequently. Defaults to `0.7`.
 - `"prompt_config"`: (*Body parameter*), `object`
  Instructions for the LLM to follow. A `prompt_config` object may contain the following attributes:
  - `"system"`: `string` The prompt content.
@@ -3071,11 +3079,11 @@ curl --request PUT \
  - `"temperature"`: `float`
    Controls the randomness of the model's predictions. A lower temperature results in more conservative responses, while a higher temperature yields more creative and diverse responses. Defaults to `0.1`.
  - `"top_p"`: `float`
-    Also known as “nucleus sampling”, this parameter sets a threshold to select a smaller set of words to sample from. It focuses on the most likely words, cutting off the less probable ones. Defaults to `0.3`
+    Also known as "nucleus sampling", this parameter sets a threshold to select a smaller set of words to sample from. It focuses on the most likely words, cutting off the less probable ones. Defaults to `0.3`
  - `"presence_penalty"`: `float`
    This discourages the model from repeating the same information by penalizing words that have already appeared in the conversation. Defaults to `0.4`.
  - `"frequency penalty"`: `float`
-    Similar to the presence penalty, this reduces the model’s tendency to repeat the same words frequently. Defaults to `0.7`.
+    Similar to the presence penalty, this reduces the model's tendency to repeat the same words frequently. Defaults to `0.7`.
 - `"prompt_config"`: (*Body parameter*), `object`
 - `"similarity_threshold"`: (*Body parameter*), `float`
 - `"vector_similarity_weight"`: (*Body parameter*), `float`
@@ -3326,6 +3334,10 @@ Failure:

 Deletes chat assistants by ID.

+:::caution DEPRECATED
+The `chat_id` in the request body is deprecated, please use `ids` list.
+:::
+
 #### Request

 - Method: DELETE
@@ -3584,6 +3596,10 @@ Failure:

 Updates a session of a specified chat assistant.

+:::caution DEPRECATED
+The previous endpoint `PUT /api/v1/chats/{chat_id}/sessions/{session_id}` is deprecated. Please use this endpoint instead.
+:::
+
 #### Request

 - Method: PATCH
@@ -4009,6 +4025,10 @@ Failure:

 Starts a chat completion request. The same endpoint supports three modes:

+:::caution DEPRECATED
+The previous endpoint `POST /api/v1/chats/{chat_id}/completions` is deprecated. Please use this endpoint instead.
+:::
+
 - No `chat_id`: talk directly with the tenant's default chat model.
 - With `chat_id` but no `session_id`: use that chat's configuration and automatically create a new session.
 - With both `chat_id` and `session_id`: continue an existing chat session.
@@ -5215,6 +5235,10 @@ Failure:

 Generates five to ten alternative question strings from the user's original query to retrieve more relevant search results.

+:::caution DEPRECATED
+The previous endpoint `POST /api/v1/sessions/related_questions` is deprecated. Please use this endpoint instead.
+:::
+
 This operation requires a `Bearer Login Token`, which typically expires with in 24 hours. You can find it in the Request Headers in your browser easily as shown below:

 ![Image](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/login_token.jpg)
@@ -6441,7 +6465,7 @@ Success
    "data": [
        {
            "agent_id": "8db9c8eddfcc11f0b5da84ba59bc53c7",
-            "content": "User Input: who am I?\nAgent Response: To address the question \"who am I?\", let's follow the logical steps outlined in the instructions:\n\n1. **Understand the User’s Request**: The user is asking for a clarification or identification of their own self. This is a fundamental question about personal identity.\n\n2. **Decompose the Request**: The request is quite simple and doesn't require complex decomposition. The core task is to provide an answer that identifies the user in some capacity.\n\n3. **Execute the Subtask**:\n   - **Identify the nature of the question**: The user is seeking to understand their own existence or their sense of self.\n   - **Assess the context**: The context is not explicitly given, so the response will be general.\n   - **Provide a response**: The answer should acknowledge the user's inquiry into their identity.\n\n4. **Validate Accuracy and Consistency**: The response should be consistent with the general understanding of the question. Since the user has not provided specific details about their identity, the response should be broad and open-ended.\n\n5. **Summarize the Final Result**: The user is asking \"who am I?\" which is an inquiry into their own identity. The answer is that the user is the individual who is asking the question. Without more specific information, a detailed description of their identity cannot be provided.\n\nSo, the final summary would be:\n\nThe user is asking the question \"who am I?\" to seek an understanding of their own identity. The response to this question is that the user is the individual who is posing the question. Without additional context or details, a more comprehensive description of the user's identity cannot be given.",
+            "content": "User Input: who am I?\nAgent Response: To address the question \"who am I?\", let's follow the logical steps outlined in the instructions:\n\n1. **Understand the User's Request**: The user is asking for a clarification or identification of their own self. This is a fundamental question about personal identity.\n\n2. **Decompose the Request**: The request is quite simple and doesn't require complex decomposition. The core task is to provide an answer that identifies the user in some capacity.\n\n3. **Execute the Subtask**:\n   - **Identify the nature of the question**: The user is seeking to understand their own existence or their sense of self.\n   - **Assess the context**: The context is not explicitly given, so the response will be general.\n   - **Provide a response**: The answer should acknowledge the user's inquiry into their identity.\n\n4. **Validate Accuracy and Consistency**: The response should be consistent with the general understanding of the question. Since the user has not provided specific details about their identity, the response should be broad and open-ended.\n\n5. **Summarize the Final Result**: The user is asking \"who am I?\" which is an inquiry into their own identity. The answer is that the user is the individual who is asking the question. Without more specific information, a detailed description of their identity cannot be provided.\n\nSo, the final summary would be:\n\nThe user is asking the question \"who am I?\" to seek an understanding of their own identity. The response to this question is that the user is the individual who is posing the question. Without additional context or details, a more comprehensive description of the user's identity cannot be given.",
            "forget_at": "None",
            "invalid_at": "None",
            "memory_id": "6c8983badede11f083f184ba59bc53c7",
@@ -6632,7 +6656,11 @@ Failure

 **GET** `/api/v1/system/healthz`

-Check the health status of RAGFlow’s dependencies (database, Redis, document engine, object storage).
+Check the health status of RAGFlow's dependencies (database, Redis, document engine, object storage).
+
+:::caution DEPRECATED
+The previous endpoint `GET /v1/system/healthz` is deprecated. Please use this endpoint instead.
+:::

 #### Request

@@ -6713,6 +6741,10 @@ Explanation:
 ```bash
 curl --request POST \
     --url http://{address}/api/v1/files \
+     --header 'Content-Type: multipart/form-data' \
+     --header 'Authorization: Bearer <YOUR_API_KEY>' \
+     --form 'file=@./test1.txt' \
+     --form 'file=@./test2.pdf' \
     --form 'parent_id={folder_id}'
 ```

@@ -6912,6 +6944,10 @@ Failure:

 ```bash
 curl --request POST \
+     --url http://{address}/api/v1/files \
+     --header 'Content-Type: application/json' \
+     --header 'Authorization: Bearer <YOUR_API_KEY>' \
+     --data '{
          "name": "New Folder",
          "type": "folder",
          "parent_id": "{folder_id}"
@@ -6984,6 +7020,10 @@ Failure:
 ```

 ##### Request parameters
+
+- `parent_id`: (*Filter parameter*), `string`
+  The folder ID to list files from. If not specified, the root folder is used by default.
+- `keywords`: (*Filter parameter*), `string`
  Search keyword to filter files by name.
 - `page`: (*Filter parameter*), `integer`
  Specifies the page on which the files will be displayed. Defaults to `1`.
@@ -7059,6 +7099,10 @@ Failure:
 ```

 ##### Request parameters
+
+- `file_id`: (*Path parameter*), `string`, *Required*
+  The ID of the file whose immediate parent folder to retrieve.
+
 #### Response

 Success:
@@ -7112,6 +7156,10 @@ Failure:
 ```

 ##### Request parameters
+
+- `file_id`: (*Path parameter*), `string`, *Required*
+  The ID of the file whose parent folders to retrieve.
+
 #### Response

 Success:
@@ -7171,6 +7219,10 @@ Failure:
 curl --request DELETE \
     --url http://{address}/api/v1/files \
     --header 'Content-Type: application/json' \
+     --header 'Authorization: Bearer <YOUR_API_KEY>' \
+     --data '{
+          "ids": ["file_id_1", "file_id_2"]
+     }'
 ```

 ##### Request parameters
@@ -7226,6 +7278,10 @@ Failure:
     --output ./downloaded_file.txt
 ```

+##### Request parameters
+
+- `file_id`: (*Path parameter*), `string`, *Required*
+  The ID of the file to download.

 #### Response

@@ -7270,6 +7326,10 @@ Failure:
  - `"dest_file_id"`: `string`, *Optional*
  - `"new_name"`: `string`, *Optional*

+##### Request examples
+
+Move files to a folder:
+
 ```bash
 curl --request POST \
     --url http://{address}/api/v1/files/move \