RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
Docs: API changes (#20290)
Wang Qie18e93bb9c75
diff --git a/docs/references/http_api_reference.md b/docs/references/http_api_reference.mdindex 5f3957b72e..5de27d5f14 100644--- a/docs/references/http_api_reference.md+++ b/docs/references/http_api_reference.md@@ -7,7 +7,7 @@ sidebar_custom_props: {---# HTTP API-A complete reference for RAGFlow's RESTful API. Before proceeding, please ensure you [have your RAGFlow API key ready for authentication](https://ragflow.io/docs/dev/acquire_ragflow_api_key).+A complete reference for RAGFlow's RESTful API, including migration notes for the 1.0 Go backend. Before proceeding, please ensure you [have your RAGFlow API key ready for authentication](https://ragflow.io/docs/dev/acquire_ragflow_api_key).---@@ -49,11 +49,27 @@ RAGFlow responses may contain both an HTTP status code and a business code in th| 500 | Server error |----## Deprecated API Aliases+## Migrate to 1.0-The following v0.24.0 REST API paths are deprecated. They remain available through the backward compatibility layer, but new integrations should use the replacement endpoints.+RAGFlow 1.0 moves the public REST API from the Python backend to Go. The canonical endpoints documented below remain available.-| Deprecated endpoint | Replacement endpoint |+The following changes require client updates:++| Area | RAGFlow 1.0 Go change | Client action |+|------|------------------------|---------------|+| Dataset parser selection | Dataset create and update use `parser_id`; responses use the canonical value `general` instead of the legacy `chunk_method: "naive"`. | Replace `chunk_method` with `parser_id`. For the general parser, send `"parser_id": "general"`. |+| Dataset parser configuration | Go stores and returns component-scoped parser settings. Most legacy top-level `parser_config` fields are not mapped into that component structure. | Read the returned component map and send component-scoped keys when changing parser settings. |+| Errors and authentication | Some validation business codes, messages, and authentication HTTP statuses differ from Python. | Branch on documented codes rather than exact message text. |++:::note+Go responses include `X-API-Source: go`, which can be used to verify the serving backend during rollout.+:::++### Removed API aliases++The following paths remain available only on the Python backend. They are not registered by the RAGFlow 1.0 Go backend.++| Removed endpoint | Replacement endpoint ||-----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|| **POST** `/api/v1/chats_openai/{chat_id}/chat/completions` | **POST** `/api/v1/openai/{chat_id}/chat/completions` || **PUT** `/api/v1/chats/{chat_id}/sessions/{session_id}` | **PATCH** `/api/v1/chats/{chat_id}/sessions/{session_id}` |@@ -73,7 +89,7 @@ The following v0.24.0 REST API paths are deprecated. They remain available throu| **GET** `/api/v1/file/get/{file_id}` | **GET** `/api/v1/files/{file_id}` || **POST** `/api/v1/file/mv` | **POST** `/api/v1/files/move` || **POST** `/api/v1/file/convert` | **POST** `/api/v1/files/link-to-datasets` |-| **POST** `/api/v1/agents_openai/{agent_id}/chat/completions` | **POST** `/api/v1/agents/chat/completions` with `"openai-compatible": true` |+| **POST** `/api/v1/agents_openai/{agent_id}/chat/completions` | **POST** `/api/v1/agents/chat/completions` with `"openai-compatible": true` |---@@ -87,8 +103,8 @@ The following v0.24.0 REST API paths are deprecated. They remain available throuCreates a model response for a given chat conversation.-:::caution DEPRECATED-`POST /api/v1/chats_openai/{chat_id}/chat/completions` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`POST /api/v1/chats_openai/{chat_id}/chat/completions` is not available in 1.0. 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).@@ -101,7 +117,7 @@ This API follows the same request and response format as OpenAI's API. It allows- `'content-Type: application/json'`- `'Authorization: Bearer <YOUR_API_KEY>'`- Body:- - `"model"`: `string`+ - `"model"`: `string` (optional)- `"messages"`: `object list`- `"stream"`: `boolean`- `"extra_body"`: `object` (optional)@@ -142,7 +158,7 @@ curl --request POST \- `chat_id` (*Path parameter*) `string`, *Required*Existing chat assistant ID. The request will use that chat assistant's knowledge and settings.-- `model` (*Body parameter*) `string`, *Required*+- `model` (*Body parameter*) `string`The model used to generate the response. When `chat_id` is provided, you may also use the legacy placeholder value `"model"` to keep using the chat assistant's configured model.- `messages` (*Body parameter*) `list[object]`, *Required*@@ -239,13 +255,13 @@ Failure:----### Create agent completion+### Create OpenAI-compatible agent completion-:::caution DEPRECATED-This endpoint remains available for backward compatibility but may be removed in a future release. New integrations should use `POST /api/v1/agents/chat/completions` with `"openai-compatible": true`.+:::caution REMOVED ALIAS+RAGFlow 1.0 Go does not serve `POST /api/v1/agents_openai/{agent_id}/chat/completions`. Use the endpoint below and move `agent_id` into the request body.:::-**POST** `/api/v1/agents_openai/{agent_id}/chat/completions`+**POST** `/api/v1/agents/chat/completions`Creates a model response for a given chat conversation.@@ -254,23 +270,28 @@ This API follows the same request and response format as OpenAI's API. It allows#### Request- Method: POST-- URL: `/api/v1/agents_openai/{agent_id}/chat/completions`+- URL: `/api/v1/agents/chat/completions`- Headers:- `'content-Type: application/json'`- `'Authorization: Bearer <YOUR_API_KEY>'`- Body:+ - `"agent_id"`: `string`+ - `"openai-compatible"`: `boolean` (must be `true`)- `"model"`: `string`- `"messages"`: `object list`- `"stream"`: `boolean`+ - `"session_id"`: `string` (optional)##### Request example```bashcurl --request POST \- --url http://{address}/api/v1/agents_openai/{agent_id}/chat/completions \+ --url http://{address}/api/v1/agents/chat/completions \--header 'Content-Type: application/json' \--header 'Authorization: Bearer <YOUR_API_KEY>' \--data '{+ "agent_id": "AGENT_ID",+ "openai-compatible": true,"model": "model","messages": [{"role": "user", "content": "Say this is a test!"}],"stream": true@@ -279,7 +300,13 @@ curl --request POST \##### Request Parameters-- `model` (*Body parameter*) `string`, *Required*+- `agent_id` (*Body parameter*) `string`, *Required*+ The ID of the associated agent.++- `openai-compatible` (*Body parameter*) `boolean`, *Required*+ Must be `true` to enable the OpenAI-compatible response format.++- `model` (*Body parameter*) `string`The model used to generate the response. The server will parse this automatically, so you can set it to any value for now.- `messages` (*Body parameter*) `list[object]`, *Required*@@ -2116,8 +2143,8 @@ Failure:Updates content or configurations for a specified chunk.-:::caution DEPRECATED-`PUT /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`PUT /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -3364,8 +3391,8 @@ Failure:Updates a session of a specified chat assistant.-:::caution DEPRECATED-`PUT /api/v1/chats/{chat_id}/sessions/{session_id}` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`PUT /api/v1/chats/{chat_id}/sessions/{session_id}` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -3795,8 +3822,8 @@ Failure:Starts a chat completion request. The same endpoint supports three modes:-:::caution DEPRECATED-`POST /api/v1/chats/{chat_id}/completions` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`POST /api/v1/chats/{chat_id}/completions` is not available in 1.0. Use this endpoint instead.:::- No `chat_id`: talk directly with the tenant's default chat model.@@ -4348,8 +4375,8 @@ Asks a specified agent a question to start an AI-powered conversation.Uses a single completion endpoint for all agent conversations.-:::caution DEPRECATED-`POST /api/v1/agents/{agent_id}/completions` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`POST /api/v1/agents/{agent_id}/completions` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -5106,8 +5133,8 @@ Failure:Generates five to ten alternative question strings from the user's original query to retrieve more relevant search results.-:::caution DEPRECATED-`POST /api/v1/sessions/related_questions` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`POST /api/v1/sessions/related_questions` is not available in 1.0. 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:@@ -6514,8 +6541,8 @@ FailureCheck the health status of RAGFlow's dependencies (database, Redis, document engine, object storage).-:::caution DEPRECATED-`GET /v1/system/healthz` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`GET /v1/system/healthz` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -6597,8 +6624,8 @@ Explanation:Uploads one or multiple files to the system.-:::caution DEPRECATED-`POST /api/v1/file/upload` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`POST /api/v1/file/upload` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -6669,8 +6696,8 @@ Failure:Uploads a file and creates the respective document.-:::caution DEPRECATED-`POST /v1/document/upload_info` and `POST /api/v1/file/upload_info` are deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`POST /v1/document/upload_info` and `POST /api/v1/file/upload_info` are not available in 1.0. Use this endpoint instead.:::#### Request@@ -6748,8 +6775,8 @@ Failure:**GET** `/api/v1/agents/attachments/{attachment_id}/download`-:::caution DEPRECATED-The previous endpoints `GET /v1/document/download/{doc_id}` and `GET /api/v1/document/download/{doc_id}` are deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+The previous endpoints `GET /v1/document/download/{doc_id}` and `GET /api/v1/document/download/{doc_id}` are not available in 1.0. Use this endpoint instead.:::Downloads a runtime attachment previously uploaded for use in the agent system.@@ -6808,8 +6835,8 @@ Failure:Creates a new file or folder in the system.-:::caution DEPRECATED-`POST /api/v1/file/create` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`POST /api/v1/file/create` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -6884,8 +6911,8 @@ Failure:Lists files and folders under a specific folder.-:::caution DEPRECATED-`GET /api/v1/file/list` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`GET /api/v1/file/list` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -6965,8 +6992,8 @@ Failure:Retrieves the immediate parent folder information of a specified file.-:::caution DEPRECATED-`GET /api/v1/file/parent_folder?file_id=...` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`GET /api/v1/file/parent_folder?file_id=...` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -7022,8 +7049,8 @@ Failure:Retrieves all parent folders of a specified file in the folder hierarchy.-:::caution DEPRECATED-`GET /api/v1/file/all_parent_folder?file_id=...` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`GET /api/v1/file/all_parent_folder?file_id=...` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -7085,8 +7112,8 @@ Failure:Deletes one or multiple files or folders.-:::caution DEPRECATED-`POST /api/v1/file/rm` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`POST /api/v1/file/rm` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -7152,8 +7179,8 @@ Failure:Downloads a file from the system.-:::caution DEPRECATED-`GET /api/v1/file/get/{file_id}` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`GET /api/v1/file/get/{file_id}` is not available in 1.0. Use this endpoint instead.:::#### Request@@ -7200,8 +7227,8 @@ Failure:Moves and/or renames files or folders. Follows Linux `mv` semantics: at least one of `dest_file_id` or `new_name` must be provided.-:::caution DEPRECATED-The previous endpoints `POST /api/v1/file/mv` and `POST /api/v1/file/rename` are deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+The previous endpoints `POST /api/v1/file/mv` and `POST /api/v1/file/rename` are not available in 1.0. Use this endpoint instead.:::- `dest_file_id` only: move files to a new folder, names unchanged.@@ -7303,8 +7330,8 @@ orConverts files to documents and links them to specified datasets.-:::caution DEPRECATED-`POST /api/v1/file/convert` is deprecated. Use this endpoint instead.+:::caution REMOVED ALIAS+`POST /api/v1/file/convert` is not available in 1.0. Use this endpoint instead.:::#### Request