A complete reference for RAGFlow's RESTful API. Before proceeding, please ensure you have your RAGFlow API key ready for authentication.
RAGFlow RESTful API 的完整参考。在继续之前，请确保您已准备好用于身份验证的 RAGFlow API 密钥。

ERROR CODES 错误代码

Code 代码	Message 消息	Description 描述
400	Bad Request 错误请求	Invalid request parameters 无效的请求参数
401	Unauthorized 未授权	Unauthorized access 未授权访问
403	Forbidden 禁止访问	Access denied 访问被拒绝
404	Not Found 未找到	Resource not found 资源未找到
500	Internal Server Error 内部服务器错误	Server internal error 服务器内部错误
1001	Invalid Chunk ID 无效的块 ID	Invalid Chunk ID 无效的块 ID
1002	Chunk Update Failed 块更新失败	Chunk update failed 更新块失败

OpenAI-Compatible API OpenAI 兼容 API

Create chat completion 创建聊天完成

POST /api/v1/chats_openai/{chat_id}/chat/completions

Creates a model response for a given chat conversation.
为给定的聊天对话创建模型响应。

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.
该 API 遵循与 OpenAI API 相同的请求和响应格式。它允许你以与使用 OpenAI API 类似的方式与模型进行交互。

Request 请求

Method: POST 方法：POST
URL: /api/v1/chats_openai/{chat_id}/chat/completions
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "model": string
- "messages": object list
- "stream": boolean

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/chats_openai/{chat_id}/chat/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "model": "model",
        "messages": [{"role": "user", "content": "Say this is a test!"}],
        "stream": true
      }'

Request Parameters 请求参数

model (Body parameter) string, Required
model (请求体参数) 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
messages (请求体参数) list[object] , 必填
A list of historical chat messages used to generate the response. This must contain at least one message with the user role.
用于生成回复的历史聊天消息列表。其中必须至少包含一条带有 user 角色的消息。
stream (Body parameter) boolean stream (身体参数) boolean
Whether to receive the response as a stream. Set this to false explicitly if you prefer to receive the entire response in one go instead of as a stream.
是否以流的形式接收响应。如果你希望一次性接收到整个响应而不是以流的形式，请显式地将此设置为 false 。

Response 响应

Stream: 流：

{
    "id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
    "choices": [
        {
            "delta": {
                "content": "This is a test. If you have any specific questions or need information, feel",
                "role": "assistant",
                "function_call": null,
                "tool_calls": null
            },
            "finish_reason": null,
            "index": 0,
            "logprobs": null
        }
    ],
    "created": 1740543996,
    "model": "model",
    "object": "chat.completion.chunk",
    "system_fingerprint": "",
    "usage": null
}
// omit duplicated information
{"choices":[{"delta":{"content":" free to ask, and I will do my best to provide an answer based on","role":"assistant"}}]}
{"choices":[{"delta":{"content":" the knowledge I have. If your question is unrelated to the provided knowledge base,","role":"assistant"}}]}
{"choices":[{"delta":{"content":" I will let you know.","role":"assistant"}}]}
// the last chunk
{
    "id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
    "choices": [
        {
            "delta": {
                "content": null,
                "role": "assistant",
                "function_call": null,
                "tool_calls": null
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "created": 1740543996,
    "model": "model",
    "object": "chat.completion.chunk",
    "system_fingerprint": "",
    "usage": {
        "prompt_tokens": 18,
        "completion_tokens": 225,
        "total_tokens": 243
    }
}

Non-stream: 非流式

{
    "choices":[
        {
            "finish_reason":"stop",
            "index":0,
            "logprobs":null,
            "message":{
                "content":"This is a test. If you have any specific questions or need information, feel free to ask, and I will do my best to provide an answer based on the knowledge I have. If your question is unrelated to the provided knowledge base, I will let you know.",
                "role":"assistant"
            }
        }
    ],
    "created":1740543499,
    "id":"chatcmpl-3a9c3572f29311efa69751e139332ced",
    "model":"model",
    "object":"chat.completion",
    "usage":{
        "completion_tokens":246,
        "completion_tokens_details":{
            "accepted_prediction_tokens":246,
            "reasoning_tokens":18,
            "rejected_prediction_tokens":0
        },
        "prompt_tokens":18,
        "total_tokens":264
    }
}

Failure: 失败：

{
  "code": 102,
  "message": "The last content of this conversation is not from user."
}

Create agent completion 创建代理完成

POST /api/v1/agents_openai/{agent_id}/chat/completions

Creates a model response for a given chat conversation.
为给定的聊天对话创建模型响应。

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.
该 API 遵循与 OpenAI API 相同的请求和响应格式。它允许您以与使用 OpenAI API 类似的方式与模型进行交互。

Request 请求

Method: POST 方法：POST
URL: /api/v1/agents_openai/{agent_id}/chat/completions
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "model": string
- "messages": object list
- "stream": boolean

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/agents_openai/{agent_id}/chat/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "model": "model",
        "messages": [{"role": "user", "content": "Say this is a test!"}],
        "stream": true
      }'

Request Parameters 请求参数

model (Body parameter) string, Required The model used to generate the response. The server will parse this automatically, so you can set it to any value for now.
model (Body 参数) string , 必填生成响应所使用的模型。服务器将自动解析此参数，因此目前可以设置为任何值。
messages (Body parameter) list[object], Required A list of historical chat messages used to generate the response. This must contain at least one message with the user role.
messages (Body 参数) list[object] , 必填用于生成响应的历史聊天消息列表。此列表必须至少包含一条具有 user 角色的消息。
stream (Body parameter) boolean Whether to receive the response as a stream. Set this to false explicitly if you prefer to receive the entire response in one go instead of as a stream.
stream (Body 参数) boolean 是否以流的形式接收响应。如果你希望一次性接收整个响应而不是以流的形式，请显式地将此参数设置为 false 。

Response 响应

Stream: 流：

{
    "id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
    "choices": [
        {
            "delta": {
                "content": "This is a test. If you have any specific questions or need information, feel",
                "role": "assistant",
                "function_call": null,
                "tool_calls": null
            },
            "finish_reason": null,
            "index": 0,
            "logprobs": null
        }
    ],
    "created": 1740543996,
    "model": "model",
    "object": "chat.completion.chunk",
    "system_fingerprint": "",
    "usage": null
}
// omit duplicated information
{"choices":[{"delta":{"content":" free to ask, and I will do my best to provide an answer based on","role":"assistant"}}]}
{"choices":[{"delta":{"content":" the knowledge I have. If your question is unrelated to the provided knowledge base,","role":"assistant"}}]}
{"choices":[{"delta":{"content":" I will let you know.","role":"assistant"}}]}
// the last chunk
{
    "id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
    "choices": [
        {
            "delta": {
                "content": null,
                "role": "assistant",
                "function_call": null,
                "tool_calls": null
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "created": 1740543996,
    "model": "model",
    "object": "chat.completion.chunk",
    "system_fingerprint": "",
    "usage": {
        "prompt_tokens": 18,
        "completion_tokens": 225,
        "total_tokens": 243
    }
}

Non-stream: 非流式

{
    "choices":[
        {
            "finish_reason":"stop",
            "index":0,
            "logprobs":null,
            "message":{
                "content":"This is a test. If you have any specific questions or need information, feel free to ask, and I will do my best to provide an answer based on the knowledge I have. If your question is unrelated to the provided knowledge base, I will let you know.",
                "role":"assistant"
            }
        }
    ],
    "created":1740543499,
    "id":"chatcmpl-3a9c3572f29311efa69751e139332ced",
    "model":"model",
    "object":"chat.completion",
    "usage":{
        "completion_tokens":246,
        "completion_tokens_details":{
            "accepted_prediction_tokens":246,
            "reasoning_tokens":18,
            "rejected_prediction_tokens":0
        },
        "prompt_tokens":18,
        "total_tokens":264
    }
}

Failure: 失败：

{
  "code": 102,
  "message": "The last content of this conversation is not from user."
}

DATASET MANAGEMENT 数据集管理

Create dataset 创建数据集

POST /api/v1/datasets

Creates a dataset. 创建一个数据集。

Request 请求

Method: POST 方法：POST
URL: /api/v1/datasets
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "name": string
- "avatar": string
- "description": string
- "embedding_model": string
- "permission": string
- "chunk_method": string
- "parser_config": object

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
      "name": "test_1"
      }'

Request parameters 请求参数

"name": (Body parameter), string, Required
"name" : (请求体参数), string , 必填
The unique name of the dataset to create. It must adhere to the following requirements:
要创建的数据集的唯一名称。它必须满足以下要求：
- Basic Multilingual Plane (BMP) only
  仅限基本多文种平面（BMP）
- Maximum 128 characters 最多 128 个字符
- Case-insensitive 不区分大小写
"avatar": (Body parameter), string
"avatar" : (主体参数), string
Base64 encoding of the avatar.
头像的 Base64 编码
- Maximum 65535 characters
  最多 65535 个字符
"description": (Body parameter), string
"description" ：(主体参数), string
A brief description of the dataset to create.
简要描述创建数据集的内容。
- Maximum 65535 characters
  最多 65535 个字符
"embedding_model": (Body parameter), string
"embedding_model" : (主体参数), string
The name of the embedding model to use. For example: "BAAI/bge-large-zh-v1.5@BAAI"
使用嵌入模型的名称。例如： "BAAI/bge-large-zh-v1.5@BAAI"
- Maximum 255 characters 最多 255 个字符
- Must follow model_name@model_factory format 必须遵循 model_name@model_factory 格式
"permission": (Body parameter), string
"permission" : (主体参数), string
Specifies who can access the dataset to create. Available options:
指定谁可以访问创建数据集。可用选项：
- "me": (Default) Only you can manage the dataset.
  "me" : (默认) 只有你可以管理数据集。
- "team": All team members can manage the dataset.
  "team" : 所有团队成员都可以管理数据集。
"chunk_method": (Body parameter), enum<string>
"chunk_method" : (主体参数), enum<string>
The chunking method of the dataset to create. Available options:
数据集的切分方法。可选选项：
- "naive": General (default) "naive" : 普通型（默认）
- "book": Book "book" : 书籍
- "email": Email "email" : 邮件
- "laws": Laws "laws" : 法律
- "manual": Manual "manual" : 手册
- "one": One "one" : 一
- "paper": Paper "paper" : 纸张
- "picture": Picture "picture" : 图片
- "presentation": Presentation "presentation" : 演讲
- "qa": Q&A "qa" : 问答
- "table": Table "table" : 表格
- "tag": Tag "tag" : 标签
"parser_config": (Body parameter), object
"parser_config" : (主体参数), object
The configuration settings for the dataset parser. The attributes in this JSON object vary with the selected "chunk_method":
数据集解析器的配置设置。此 JSON 对象中的属性随所选 "chunk_method" 而变化：
- If "chunk_method" is "naive", the "parser_config" object contains the following attributes:
  如果 "chunk_method" 是 "naive" ，则 "parser_config" 对象包含以下属性：
  - "auto_keywords": int
    - Defaults to 0 默认为 0
    - Minimum: 0 最小值： 0
    - Maximum: 32 最大值： 32
  - "auto_questions": int
    - Defaults to 0 默认值： 0
    - Minimum: 0 最小值： 0
    - Maximum: 10 最大值： 10
  - "chunk_token_num": int
    - Defaults to 128 默认值： 128
    - Minimum: 1 最小值： 1
    - Maximum: 2048 最大值： 2048
  - "delimiter": string
    - Defaults to "\n". 默认为 "\n" 。
  - "html4excel": bool Indicates whether to convert Excel documents into HTML format.
    "html4excel" ： bool 表示是否将 Excel 文档转换为 HTML 格式。
    - Defaults to false 默认为 false
  - "layout_recognize": string
    - Defaults to DeepDOC 默认为 DeepDOC
  - "tag_kb_ids": array<string> refer to Use tag set
    "tag_kb_ids" : array<string> 指的是使用标签集
    - Must include a list of dataset IDs, where each dataset is parsed using the Tag Chunk Method
      必须包含数据集 ID 列表，其中每个数据集都使用标签分块方法进行解析
  - "task_page_size": int For PDF only.
    "task_page_size" : int 仅适用于 PDF。
    - Defaults to 12 默认为 12
    - Minimum: 1 最小值： 1
  - "raptor": object RAPTOR-specific settings.
    "raptor" : object RAPTOR 特定设置。
    - Defaults to: {"use_raptor": false} 默认为： {"use_raptor": false}
  - "graphrag": object GRAPHRAG-specific settings.
    "graphrag" : object GRAPHRAG 特定设置。
    - Defaults to: {"use_graphrag": false} 默认为： {"use_graphrag": false}
- If "chunk_method" is "qa", "manuel", "paper", "book", "laws", or "presentation", the "parser_config" object contains the following attribute:
  如果 "chunk_method" 是 "qa" 、 "manuel" 、 "paper" 、 "book" 、 "laws" 或 "presentation" ，则 "parser_config" 对象包含以下属性：
  - "raptor": object RAPTOR-specific settings.
    "raptor" ： object RAPTOR 特定的设置。
    - Defaults to: {"use_raptor": false}. 默认为： {"use_raptor": false} 。
- If "chunk_method" is "table", "picture", "one", or "email", "parser_config" is an empty JSON object.
  如果 "chunk_method" 是 "table" 、 "picture" 、 "one" 或 "email" ， "parser_config" 是一个空的 JSON 对象。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": {
        "avatar": null,
        "chunk_count": 0,
        "chunk_method": "naive",
        "create_date": "Mon, 28 Apr 2025 18:40:41 GMT",
        "create_time": 1745836841611,
        "created_by": "3af81804241d11f0a6a79f24fc270c7f",
        "description": null,
        "document_count": 0,
        "embedding_model": "BAAI/bge-large-zh-v1.5@BAAI",
        "id": "3b4de7d4241d11f0a6a79f24fc270c7f",
        "language": "English",
        "name": "RAGFlow example",
        "pagerank": 0,
        "parser_config": {
            "chunk_token_num": 128, 
            "delimiter": "\\n!?;。；！？", 
            "html4excel": false, 
            "layout_recognize": "DeepDOC", 
            "raptor": {
                "use_raptor": false
                }
            },
        "permission": "me",
        "similarity_threshold": 0.2,
        "status": "1",
        "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
        "token_num": 0,
        "update_date": "Mon, 28 Apr 2025 18:40:41 GMT",
        "update_time": 1745836841611,
        "vector_similarity_weight": 0.3,
    },
}

Failure: 失败：

{
    "code": 101,
    "message": "Dataset name 'RAGFlow example' already exists"
}

Delete datasets 删除数据集

DELETE /api/v1/datasets 删除 /api/v1/datasets

Deletes datasets by ID.
通过 ID 删除数据集。

Request 请求

Method: DELETE 方法：DELETE
URL: /api/v1/datasets
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
- Body:
  - "ids": list[string] or null
    "ids" : list[string] 或 null

Request example 请求示例

curl --request DELETE \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["d94a8dc02c9711f0930f7fbc369eab6d", "e94a8dc02c9711f0930f7fbc369eab6e"]
     }'

Request parameters 请求参数

"ids": (Body parameter), list[string] or null, Required
"ids" : (身体参数), list[string] 或 null , 必填
Specifies the datasets to delete:
指定要删除的数据集：
- If null, all datasets will be deleted.
  如果 null , 将删除所有数据集。
- If an array of IDs, only the specified datasets will be deleted.
  如果是 ID 数组，则仅删除指定的数据集。
- If an empty array, no datasets will be deleted.
  如果是一个空数组，则不会删除任何数据集。

Response 响应

Success: 成功：

{
    "code": 0 
}

Failure: 失败：

{
    "code": 102,
    "message": "You don't own the dataset."
}

Update dataset 更新数据集

PUT /api/v1/datasets/{dataset_id}

Updates configurations for a specified dataset.
更新指定数据集的配置。

Request 请求

Method: PUT 方法：PUT
URL: /api/v1/datasets/{dataset_id}
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "name": string
- "avatar": string
- "description": string
- "embedding_model": string
- "permission": string
- "chunk_method": string
- "pagerank": int
- "parser_config": object

Request example 请求示例

curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "name": "updated_dataset"
     }'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The ID of the dataset to update.
要更新的数据集的 ID。
"name": (Body parameter), string
"name" : (主体参数), string
The revised name of the dataset.
数据集的修订名称。
- Basic Multilingual Plane (BMP) only
  仅限基本多文种平面（BMP）
- Maximum 128 characters 最多 128 个字符
- Case-insensitive 不区分大小写
"avatar": (Body parameter), string
"avatar" : (主体参数), string
The updated base64 encoding of the avatar.
头像的更新 base64 编码。
- Maximum 65535 characters
  最多 65535 个字符
"embedding_model": (Body parameter), string
"embedding_model" : (主体参数), string
The updated embedding model name.
更新后的嵌入模型名称。
- Ensure that "chunk_count" is 0 before updating "embedding_model".
  更新 "embedding_model" 之前，请确保 "chunk_count" 是 0 。
- Maximum 255 characters 最多 255 个字符
- Must follow model_name@model_factory format 必须遵循 model_name@model_factory 格式
"permission": (Body parameter), string
"permission" : (主体参数), string
The updated dataset permission. Available options:
更新后的数据集权限。可用选项：
- "me": (Default) Only you can manage the dataset.
  "me" : (默认) 只有你可以管理数据集。
- "team": All team members can manage the dataset.
  "team" : 所有团队成员都可以管理数据集。
"pagerank": (Body parameter), int
"pagerank" : (主体参数), int
refer to Set page rank
参考设置页面排名
- Default: 0 默认： 0
- Minimum: 0 最小值： 0
- Maximum: 100 最大值： 100
"chunk_method": (Body parameter), enum<string>
"chunk_method" : (主体参数), enum<string>
The chunking method for the dataset. Available options:
数据集的分块方法。可用选项：
- "naive": General (default) "naive" : 通用（默认）
- "book": Book "book" : 书籍
- "email": Email "email" : 邮件
- "laws": Laws "laws" : 法律
- "manual": Manual "manual" : 手册
- "one": One "one" : 一
- "paper": Paper "paper" : 论文
- "picture": Picture "picture" : 图片
- "presentation": Presentation "presentation" : 演讲
- "qa": Q&A "qa" : 问答
- "table": Table "table" : 表格
- "tag": Tag "tag" : 标签
"parser_config": (Body parameter), object
"parser_config" : (主体参数), object
The configuration settings for the dataset parser. The attributes in this JSON object vary with the selected "chunk_method":
数据集解析器的配置设置。此 JSON 对象中的属性随所选的 "chunk_method" :
- If "chunk_method" is "naive", the "parser_config" object contains the following attributes:
  如果 "chunk_method" 是 "naive" ，则 "parser_config" 对象包含以下属性：
  - "auto_keywords": int
    - Defaults to 0 默认为 0
    - Minimum: 0 最小值： 0
    - Maximum: 32 最大值： 32
  - "auto_questions": int
    - Defaults to 0 默认为 0
    - Minimum: 0 最小值： 0
    - Maximum: 10 最大值： 10
  - "chunk_token_num": int
    - Defaults to 128 默认为 128
    - Minimum: 1 最小值： 1
    - Maximum: 2048 最大值： 2048
  - "delimiter": string
    - Defaults to "\n". 默认为 "\n" 。
  - "html4excel": bool Indicates whether to convert Excel documents into HTML format.
    "html4excel" : bool 指示是否将 Excel 文档转换为 HTML 格式。
    - Defaults to false 默认为 false
  - "layout_recognize": string
    - Defaults to DeepDOC 默认为 DeepDOC
  - "tag_kb_ids": array<string> refer to Use tag set
    "tag_kb_ids" : array<string> 指的是使用标签集
    - Must include a list of dataset IDs, where each dataset is parsed using the Tag Chunk Method
      必须包含数据集 ID 列表，其中每个数据集都使用标签分块方法进行解析
  - "task_page_size": int For PDF only.
    "task_page_size" : int 仅适用于 PDF。
    - Defaults to 12 默认为 12
    - Minimum: 1 最小值： 1
  - "raptor": object RAPTOR-specific settings.
    "raptor" ： object RAPTOR 特定的设置。
    - Defaults to: {"use_raptor": false} 默认为： {"use_raptor": false}
  - "graphrag": object GRAPHRAG-specific settings.
    "graphrag" : object GRAPHRAG 特定设置。
    - Defaults to: {"use_graphrag": false} 默认为： {"use_graphrag": false}
- If "chunk_method" is "qa", "manuel", "paper", "book", "laws", or "presentation", the "parser_config" object contains the following attribute:
  如果 "chunk_method" 是 "qa" 、 "manuel" 、 "paper" 、 "book" 、 "laws" 或 "presentation" ，则 "parser_config" 对象包含以下属性：
  - "raptor": object RAPTOR-specific settings.
    "raptor" ： object RAPTOR 特定的设置。
    - Defaults to: {"use_raptor": false}. 默认为： {"use_raptor": false} 。
- If "chunk_method" is "table", "picture", "one", or "email", "parser_config" is an empty JSON object.
  如果 "chunk_method" 是 "table" 、 "picture" 、 "one" 或 "email" ， "parser_config" 是一个空的 JSON 对象。

Response 响应

Success: 成功：

{
    "code": 0 
}

Failure: 失败：

{
    "code": 102,
    "message": "Can't change tenant_id."
}

List datasets 列出数据集

GET /api/v1/datasets?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id}

Lists datasets. 列出数据集。

Request 请求

Method: GET 方法：GET
URL: /api/v1/datasets?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id}
Headers:
- 'Authorization: Bearer <YOUR_API_KEY>'

Request example 请求示例

curl --request GET \
     --url http://{address}/api/v1/datasets?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Request parameters 请求参数

page: (Filter parameter) page : (过滤参数)
Specifies the page on which the datasets will be displayed. Defaults to 1.
指定数据集将显示的页面。默认为 1 。
page_size: (Filter parameter) page_size : (过滤参数)
The number of datasets on each page. Defaults to 30.
每页显示的数据集数量。默认为 30 。
orderby: (Filter parameter) orderby : (过滤参数)
The field by which datasets should be sorted. Available options:
数据集排序的字段。可用选项：
- create_time (default) create_time (默认)
- update_time
desc: (Filter parameter) desc : (过滤参数)
Indicates whether the retrieved datasets should be sorted in descending order. Defaults to true.
指示检索的数据集是否应按降序排序。默认为 true 。
name: (Filter parameter) name ：（过滤参数）
The name of the dataset to retrieve.
要检索的数据集的名称。
id: (Filter parameter) id ：（过滤参数）
The ID of the dataset to retrieve.
获取数据集的 ID。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": [
        {
            "avatar": "",
            "chunk_count": 59,
            "create_date": "Sat, 14 Sep 2024 01:12:37 GMT",
            "create_time": 1726276357324,
            "created_by": "69736c5e723611efb51b0242ac120007",
            "description": null,
            "document_count": 1,
            "embedding_model": "BAAI/bge-large-zh-v1.5",
            "id": "6e211ee0723611efa10a0242ac120007",
            "language": "English",
            "name": "mysql",
            "chunk_method": "naive",
            "parser_config": {
                "chunk_token_num": 8192,
                "delimiter": "\\n",
                "entity_types": [
                    "organization",
                    "person",
                    "location",
                    "event",
                    "time"
                ]
            },
            "permission": "me",
            "similarity_threshold": 0.2,
            "status": "1",
            "tenant_id": "69736c5e723611efb51b0242ac120007",
            "token_num": 12744,
            "update_date": "Thu, 10 Oct 2024 04:07:23 GMT",
            "update_time": 1728533243536,
            "vector_similarity_weight": 0.3
        }
    ]
}

Failure: 失败：

{
    "code": 102,
    "message": "The dataset doesn't exist"
}

FILE MANAGEMENT WITHIN DATASET
数据集中的文件管理

Upload documents 上传文档

POST /api/v1/datasets/{dataset_id}/documents

Uploads documents to a specified dataset.
将文档上传到指定的数据集。

Request 请求

Method: POST 方法：POST
URL: /api/v1/datasets/{dataset_id}/documents
Headers:
- 'Content-Type: multipart/form-data'
- 'Authorization: Bearer <YOUR_API_KEY>'
Form: 表单：
- 'file=@{FILE_PATH}'

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents \
     --header 'Content-Type: multipart/form-data' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --form 'file=@./test1.txt' \
     --form 'file=@./test2.pdf'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The ID of the dataset to which the documents will be uploaded.
数据集的 ID，文档将上传到该数据集。
'file': (Body parameter) 'file' : (主体参数)
A document to upload.
要上传的文档。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": [
        {
            "chunk_method": "naive",
            "created_by": "69736c5e723611efb51b0242ac120007",
            "dataset_id": "527fa74891e811ef9c650242ac120006",
            "id": "b330ec2e91ec11efbc510242ac120004",
            "location": "1.txt",
            "name": "1.txt",
            "parser_config": {
                "chunk_token_num": 128,
                "delimiter": "\\n",
                "html4excel": false,
                "layout_recognize": true,
                "raptor": {
                    "use_raptor": false
                }
            },
            "run": "UNSTART",
            "size": 17966,
            "thumbnail": "",
            "type": "doc"
        }
    ]
}

Failure: 失败：

{
    "code": 101,
    "message": "No file part!"
}

Update document 更新文档

PUT /api/v1/datasets/{dataset_id}/documents/{document_id}

Updates configurations for a specified document.
更新指定文档的配置。

Request 请求

Method: PUT 方法：PUT
URL: /api/v1/datasets/{dataset_id}/documents/{document_id}
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "name":string
- "meta_fields":object
- "chunk_method":string
- "parser_config":object

Request example 请求示例

curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/info/{document_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
     {
          "name": "manual.txt", 
          "chunk_method": "manual", 
          "parser_config": {"chunk_token_count": 128}
     }'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The ID of the associated dataset.
关联数据集的 ID。
document_id: (Path parameter) document_id : (路径参数)
The ID of the document to update.
更新文档的 ID。
"name": (Body parameter), string
"name" : (主体参数), string
"meta_fields": (Body parameter), dict[str, Any] The meta fields of the document.
"meta_fields" : (正文参数), dict[str, Any] 文档的元字段。
"chunk_method": (Body parameter), string
"chunk_method" : (主体参数), string
The parsing method to apply to the document:
应用于文档的解析方法：
- "naive": General "naive" : 常规
- "manual: Manual "manual : 手册
- "qa": Q&A "qa" : 问答
- "table": Table "table" : 表格
- "paper": Paper "paper" : 论文
- "book": Book "book" : 书籍
- "laws": Laws "laws" : 法律
- "presentation": Presentation "presentation" : 演讲
- "picture": Picture "picture" : 图片
- "one": One "one" : 一
- "email": Email "email" : 邮件
"parser_config": (Body parameter), object
"parser_config" : (主体参数), object
The configuration settings for the dataset parser. The attributes in this JSON object vary with the selected "chunk_method":
数据集解析器的配置设置。此 JSON 对象中的属性随所选的 "chunk_method" 而变化：
- If "chunk_method" is "naive", the "parser_config" object contains the following attributes:
  如果 "chunk_method" 是 "naive" ，则 "parser_config" 对象包含以下属性：
  - "chunk_token_count": Defaults to 256.
    "chunk_token_count" : 默认为 256 。
  - "layout_recognize": Defaults to true.
    "layout_recognize" : 默认为 true 。
  - "html4excel": Indicates whether to convert Excel documents into HTML format. Defaults to false.
    "html4excel" : 指示是否将 Excel 文档转换为 HTML 格式。默认为 false 。
  - "delimiter": Defaults to "\n".
    "delimiter" : 默认为 "\n" 。
  - "task_page_size": Defaults to 12. For PDF only.
    "task_page_size" : 默认为 12 。仅适用于 PDF。
  - "raptor": RAPTOR-specific settings. Defaults to: {"use_raptor": false}.
    "raptor" : RAPTOR 特定设置。默认为： {"use_raptor": false} 。
- If "chunk_method" is "qa", "manuel", "paper", "book", "laws", or "presentation", the "parser_config" object contains the following attribute:
  如果 "chunk_method" 是 "qa" 、 "manuel" 、 "paper" 、 "book" 、 "laws" 或 "presentation" ，则 "parser_config" 对象包含以下属性：
  - "raptor": RAPTOR-specific settings. Defaults to: {"use_raptor": false}.
    "raptor" : RAPTOR 特定设置。默认为： {"use_raptor": false} 。
- If "chunk_method" is "table", "picture", "one", or "email", "parser_config" is an empty JSON object.
  如果 "chunk_method" 是 "table" 、 "picture" 、 "one" 或 "email" ， "parser_config" 是一个空的 JSON 对象。

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "The dataset does not have the document."
}

Download document 下载文档

GET /api/v1/datasets/{dataset_id}/documents/{document_id}

Downloads a document from a specified dataset.
从指定数据集下载文档。

Request 请求

Method: GET 方法：GET
URL: /api/v1/datasets/{dataset_id}/documents/{document_id}
Headers:
- 'Authorization: Bearer <YOUR_API_KEY>'
Output: 输出：
- '{PATH_TO_THE_FILE}'

Request example 请求示例

curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --output ./ragflow.txt

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The associated dataset ID.
相关数据集 ID。
documents_id: (Path parameter) documents_id : (路径参数)
The ID of the document to download.
要下载的文档 ID。

Response 响应

Success: 成功：

This is a test to verify the file download feature.

Failure: 失败：

{
    "code": 102,
    "message": "You do not own the dataset 7898da028a0511efbf750242ac1220005."
}

List documents 列出文档

GET /api/v1/datasets/{dataset_id}/documents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&keywords={keywords}&id={document_id}&name={document_name}

Lists documents in a specified dataset.
列出指定数据集中的文档。

Request 请求

Method: GET 方法：GET
URL: /api/v1/datasets/{dataset_id}/documents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&keywords={keywords}&id={document_id}&name={document_name}
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'

Request example 请求示例

curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&keywords={keywords}&id={document_id}&name={document_name} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The associated dataset ID.
相关数据集 ID。
keywords: (Filter parameter), string
keywords : (过滤参数), string
The keywords used to match document titles.
用于匹配文档标题的关键词。
page: (Filter parameter), integer Specifies the page on which the documents will be displayed. Defaults to 1.
page : (过滤参数), integer 指定文档将显示的页面。默认为 1 。
page_size: (Filter parameter), integer
page_size : (过滤参数), integer
The maximum number of documents on each page. Defaults to 30.
每页文档的最大数量。默认为 30 。
orderby: (Filter parameter), string
orderby : (过滤参数), string
The field by which documents should be sorted. Available options:
用于对文档进行排序的字段。可选选项：
- create_time (default) create_time (默认)
- update_time
desc: (Filter parameter), boolean
desc ：(过滤参数)， boolean
Indicates whether the retrieved documents should be sorted in descending order. Defaults to true.
指示检索到的文档是否应按降序排序。默认值为 true 。
id: (Filter parameter), string
id ：（过滤参数）， string
The ID of the document to retrieve.
要检索的文档的 ID。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": {
        "docs": [
            {
                "chunk_count": 0,
                "create_date": "Mon, 14 Oct 2024 09:11:01 GMT",
                "create_time": 1728897061948,
                "created_by": "69736c5e723611efb51b0242ac120007",
                "id": "3bcfbf8a8a0c11ef8aba0242ac120006",
                "knowledgebase_id": "7898da028a0511efbf750242ac120005",
                "location": "Test_2.txt",
                "name": "Test_2.txt",
                "parser_config": {
                    "chunk_token_count": 128,
                    "delimiter": "\n",
                    "layout_recognize": true,
                    "task_page_size": 12
                },
                "chunk_method": "naive",
                "process_begin_at": null,
                "process_duation": 0.0,
                "progress": 0.0,
                "progress_msg": "",
                "run": "0",
                "size": 7,
                "source_type": "local",
                "status": "1",
                "thumbnail": null,
                "token_count": 0,
                "type": "doc",
                "update_date": "Mon, 14 Oct 2024 09:11:01 GMT",
                "update_time": 1728897061948
            }
        ],
        "total": 1
    }
}

Failure: 失败：

{
    "code": 102,
    "message": "You don't own the dataset 7898da028a0511efbf750242ac1220005. "
}

Delete documents 删除文档

DELETE /api/v1/datasets/{dataset_id}/documents 删除 /api/v1/datasets/{dataset_id}/documents

Deletes documents by ID.
通过 ID 删除文档。

Request 请求

Method: DELETE 方法：DELETE
URL: /api/v1/datasets/{dataset_id}/documents
Headers:
- 'Content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "ids": list[string]

Request example 请求示例

curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "ids": ["id_1","id_2"]
     }'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The associated dataset ID.
相关数据集 ID。
"ids": (Body parameter), list[string]
"ids" : (主体参数), list[string]
The IDs of the documents to delete. If it is not specified, all documents in the specified dataset will be deleted.
要删除的文档的 ID。如果没有指定，将删除指定数据集中的所有文档。

Response 响应

Success: 成功：

{
    "code": 0
}.

Failure: 失败：

{
    "code": 102,
    "message": "You do not own the dataset 7898da028a0511efbf750242ac1220005."
}

Parse documents 解析文档

POST /api/v1/datasets/{dataset_id}/chunks

Parses documents in a specified dataset.
解析指定数据集中的文档。

Request 请求

Method: POST 方法：POST
URL: /api/v1/datasets/{dataset_id}/chunks
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "document_ids": list[string]

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "document_ids": ["97a5f1c2759811efaa500242ac120004","97ad64b6759811ef9fc30242ac120004"]
     }'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The dataset ID. 数据集 ID。
"document_ids": (Body parameter), list[string], Required
"document_ids" : (请求体参数), list[string] , 必填
The IDs of the documents to parse.
要解析的文档 ID。

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "`document_ids` is required"
}

Stop parsing documents 停止解析文档

DELETE /api/v1/datasets/{dataset_id}/chunks 删除 /api/v1/datasets/{dataset_id}/chunks

Stops parsing specified documents.
停止解析指定的文档。

Request 请求

Method: DELETE 方法：DELETE
URL: /api/v1/datasets/{dataset_id}/chunks
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "document_ids": list[string]

Request example 请求示例

curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "document_ids": ["97a5f1c2759811efaa500242ac120004","97ad64b6759811ef9fc30242ac120004"]
     }'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The associated dataset ID.
相关数据集 ID。
"document_ids": (Body parameter), list[string], Required
"document_ids" : (请求体参数), list[string] , 必填
The IDs of the documents for which the parsing should be stopped.
用于解析应停止的文档的 ID。

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "`document_ids` is required"
}

CHUNK MANAGEMENT WITHIN DATASET
数据集中的块管理

Add chunk 添加片段

POST /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

Adds a chunk to a specified document in a specified dataset.
向指定数据集中的指定文档添加片段。

Request 请求

Method: POST 方法：POST
URL: /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "content": string
- "important_keywords": list[string]

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "content": "<CHUNK_CONTENT_HERE>"
     }'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The associated dataset ID.
相关数据集 ID。
document_ids: (Path parameter) document_ids : (路径参数)
The associated document ID.
相关文档 ID。
"content": (Body parameter), string, Required
"content" : (请求体参数), string , 必填
The text content of the chunk.
该片段的文本内容。
"important_keywords(Body parameter), list[string]
"important_keywords （正文参数）， list[string]
The key terms or phrases to tag with the chunk.
用于标记该片段的关键词或短语。
"questions"(Body parameter), list[string] If there is a given question, the embedded chunks will be based on them
"questions" (体参数), list[string] 如果有给定的题目，嵌入的片段将基于它们

Response 响应

Success: 成功：

{
    "code": 0,
    "data": {
        "chunk": {
            "content": "who are you",
            "create_time": "2024-12-30 16:59:55",
            "create_timestamp": 1735549195.969164,
            "dataset_id": "72f36e1ebdf411efb7250242ac120006",
            "document_id": "61d68474be0111ef98dd0242ac120006",
            "id": "12ccdc56e59837e5",
            "important_keywords": [],
            "questions": []
        }
    }
}

Failure: 失败：

{
    "code": 102,
    "message": "`content` is required"
}

List chunks 列出片段

GET /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?keywords={keywords}&page={page}&page_size={page_size}&id={id}

Lists chunks in a specified document.
列出指定文档中的片段。

Request 请求

Method: GET 方法：GET
URL: /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?keywords={keywords}&page={page}&page_size={page_size}&id={chunk_id}
Headers:
- 'Authorization: Bearer <YOUR_API_KEY>'

Request example 请求示例

curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?keywords={keywords}&page={page}&page_size={page_size}&id={chunk_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The associated dataset ID.
相关数据集 ID。
document_id: (Path parameter) document_id : (路径参数)
The associated document ID.
相关文档 ID。
keywords(Filter parameter), string
keywords (过滤参数), string
The keywords used to match chunk content.
用于匹配块内容的键词。
page(Filter parameter), integer
page (过滤参数), integer
Specifies the page on which the chunks will be displayed. Defaults to 1.
指定块将显示的页面。默认为 1 。
page_size(Filter parameter), integer
page_size (过滤参数), integer
The maximum number of chunks on each page. Defaults to 1024.
每页上的最大块数。默认为 1024 。
id(Filter parameter), string
id (过滤参数), string
The ID of the chunk to retrieve.
要检索的块的 ID。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": {
        "chunks": [
            {
                "available": true,
                "content": "This is a test content.",
                "docnm_kwd": "1.txt",
                "document_id": "b330ec2e91ec11efbc510242ac120004",
                "id": "b48c170e90f70af998485c1065490726",
                "image_id": "",
                "important_keywords": "",
                "positions": [
                    ""
                ]
            }
        ],
        "doc": {
            "chunk_count": 1,
            "chunk_method": "naive",
            "create_date": "Thu, 24 Oct 2024 09:45:27 GMT",
            "create_time": 1729763127646,
            "created_by": "69736c5e723611efb51b0242ac120007",
            "dataset_id": "527fa74891e811ef9c650242ac120006",
            "id": "b330ec2e91ec11efbc510242ac120004",
            "location": "1.txt",
            "name": "1.txt",
            "parser_config": {
                "chunk_token_num": 128,
                "delimiter": "\\n",
                "html4excel": false,
                "layout_recognize": true,
                "raptor": {
                    "use_raptor": false
                }
            },
            "process_begin_at": "Thu, 24 Oct 2024 09:56:44 GMT",
            "process_duation": 0.54213,
            "progress": 0.0,
            "progress_msg": "Task dispatched...",
            "run": "2",
            "size": 17966,
            "source_type": "local",
            "status": "1",
            "thumbnail": "",
            "token_count": 8,
            "type": "doc",
            "update_date": "Thu, 24 Oct 2024 11:03:15 GMT",
            "update_time": 1729767795721
        },
        "total": 1
    }
}

Failure: 失败：

{
    "code": 102,
    "message": "You don't own the document 5c5999ec7be811ef9cab0242ac12000e5."
}

Delete chunks 删除片段

DELETE /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks 删除 /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

Deletes chunks by ID.
通过 ID 删除片段。

Request 请求

Method: DELETE 方法：DELETE
URL: /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "chunk_ids": list[string]

Request example 请求示例

curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "chunk_ids": ["test_1", "test_2"]
     }'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The associated dataset ID.
相关数据集 ID。
document_ids: (Path parameter) document_ids : (路径参数)
The associated document ID.
相关文档 ID。
"chunk_ids": (Body parameter), list[string]
"chunk_ids" : (主体参数), list[string]
The IDs of the chunks to delete. If it is not specified, all chunks of the specified document will be deleted.
要删除的片段的 ID。如果没有指定，将删除指定文档的所有片段。

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "`chunk_ids` is required"
}

Update chunk 更新片段

PUT /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}

Updates content or configurations for a specified chunk.
更新指定块的內容或配置。

Request 请求

Method: PUT 方法：PUT
URL: /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "content": string
- "important_keywords": list[string]
- "available": boolean

Request example 请求示例

curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {   
          "content": "ragflow123",  
          "important_keywords": []  
     }'

Request parameters 请求参数

dataset_id: (Path parameter) dataset_id : (路径参数)
The associated dataset ID.
相关数据集 ID。
document_ids: (Path parameter) document_ids : (路径参数)
The associated document ID.
相关文档 ID。
chunk_id: (Path parameter) chunk_id : (路径参数)
The ID of the chunk to update.
更新块的 ID。
"content": (Body parameter), string
"content" : (主体参数), string
The text content of the chunk.
该片段的文本内容。
"important_keywords": (Body parameter), list[string]
"important_keywords" : (主体参数), list[string]
A list of key terms or phrases to tag with the chunk.
用于标记块的键词或短语列表。
"available": (Body parameter) boolean
"available" : (主体参数) boolean
The chunk's availability status in the dataset. Value options:
块在数据集中的可用状态。值选项：
- true: Available (default)
  true : 可用（默认）
- false: Unavailable false : 不可用

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "Can't find this chunk 29a2d9987e16ba331fb4d7d30d99b71d2"
}

Retrieve chunks 检索片段

POST /api/v1/retrieval

Retrieves chunks from specified datasets.
从指定数据集中检索片段。

Request 请求

Method: POST 方法：POST
URL: /api/v1/retrieval
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "question": string
- "dataset_ids": list[string]
- "document_ids": list[string]
- "page": integer
- "page_size": integer
- "similarity_threshold": float
- "vector_similarity_weight": float
- "top_k": integer
- "rerank_id": string
- "keyword": boolean
- "highlight": boolean

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/retrieval \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "question": "What is advantage of ragflow?",
          "dataset_ids": ["b2a62730759d11ef987d0242ac120004"],
          "document_ids": ["77df9ef4759a11ef8bdd0242ac120004"]
     }'

Request parameter 请求参数

"question": (Body parameter), string, Required
"question" : (请求体参数), string , 必填
The user query or query keywords.
用户查询或查询关键词。
"dataset_ids": (Body parameter) list[string]
"dataset_ids" : (主体参数) list[string]
The IDs of the datasets to search. If you do not set this argument, ensure that you set "document_ids".
要搜索的数据集的 ID。如果您未设置此参数，请确保设置 "document_ids" 。
"document_ids": (Body parameter), list[string]
"document_ids" : (主体参数), list[string]
The IDs of the documents to search. Ensure that all selected documents use the same embedding model. Otherwise, an error will occur. If you do not set this argument, ensure that you set "dataset_ids".
要搜索的文档的 ID。确保所有选定的文档使用相同的嵌入模型。否则，将发生错误。如果您未设置此参数，请确保设置 "dataset_ids" 。
"page": (Body parameter), integer
"page" : (主体参数), integer
Specifies the page on which the chunks will be displayed. Defaults to 1.
指定块将显示的页面。默认为 1 。
"page_size": (Body parameter) "page_size" : (身体参数)
The maximum number of chunks on each page. Defaults to 30.
每页上的最大块数。默认为 30 。
"similarity_threshold": (Body parameter)
The minimum similarity score. Defaults to 0.2.
最小相似度分数。默认值为 0.2 。
"vector_similarity_weight": (Body parameter), float
"vector_similarity_weight" : (主体参数), float
The weight of vector cosine similarity. Defaults to 0.3. If x represents the weight of vector cosine similarity, then (1 - x) is the term similarity weight.
向量余弦相似度的权重。默认值为 0.3 。如果 x 表示向量余弦相似度的权重，那么 (1 - x) 是术语相似度权重。
"top_k": (Body parameter), integer
"top_k" : (主体参数), integer
The number of chunks engaged in vector cosine computation. Defaults to 1024.
参与向量余弦计算的块数。默认值为 1024 。
"rerank_id": (Body parameter), integer
"rerank_id" : (主体参数), integer
The ID of the rerank model.
重排序模型的 ID。
"keyword": (Body parameter), boolean
"keyword" : (主体参数), boolean
Indicates whether to enable keyword-based matching:
指示是否启用基于关键词的匹配：
- true: Enable keyword-based matching.
  true ：启用基于关键词的匹配。
- false: Disable keyword-based matching (default).
  false ：禁用基于关键词的匹配（默认）。
"highlight": (Body parameter), boolean
"highlight" : (主体参数), boolean
Specifies whether to enable highlighting of matched terms in the results:
指定是否在结果中高亮显示匹配的术语：
- true: Enable highlighting of matched terms.
  true ：启用匹配术语的高亮显示。
- false: Disable highlighting of matched terms (default).
  false ：禁用匹配术语的高亮显示（默认）。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": {
        "chunks": [
            {
                "content": "ragflow content",
                "content_ltks": "ragflow content",
                "document_id": "5c5999ec7be811ef9cab0242ac120005",
                "document_keyword": "1.txt",
                "highlight": "<em>ragflow</em> content",
                "id": "d78435d142bd5cf6704da62c778795c5",
                "image_id": "",
                "important_keywords": [
                    ""
                ],
                "kb_id": "c7ee74067a2c11efb21c0242ac120006",
                "positions": [
                    ""
                ],
                "similarity": 0.9669436601210759,
                "term_similarity": 1.0,
                "vector_similarity": 0.8898122004035864
            }
        ],
        "doc_aggs": [
            {
                "count": 1,
                "doc_id": "5c5999ec7be811ef9cab0242ac120005",
                "doc_name": "1.txt"
            }
        ],
        "total": 1
    }
}

Failure: 失败：

{
    "code": 102,
    "message": "`datasets` is required."
}

CHAT ASSISTANT MANAGEMENT
聊天助手管理

Create chat assistant 创建聊天助手

POST /api/v1/chats

Creates a chat assistant.
创建一个聊天助手。

Request 请求

Method: POST 方法：POST
URL: /api/v1/chats
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "name": string
- "avatar": string
- "dataset_ids": list[string]
- "llm": object
- "prompt": object

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/chats \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
    "dataset_ids": ["0b2cbc8c877f11ef89070242ac120005"],
    "name":"new_chat_1"
}'

Request parameters 请求参数

"name": (Body parameter), string, Required
"name" : (请求体参数), string , 必填
The name of the chat assistant.
聊天助手的名称。
"avatar": (Body parameter), string
"avatar" : (主体参数), string
Base64 encoding of the avatar.
头像的 Base64 编码
"dataset_ids": (Body parameter), list[string]
"dataset_ids" : (主体参数), list[string]
The IDs of the associated datasets.
关联数据集的 ID。
"llm": (Body parameter), object
"llm" : (主体参数), object
The LLM settings for the chat assistant to create. If it is not explicitly set, a JSON object with the following values will be generated as the default. An llm JSON object contains the following attributes:
聊天助手的 LLM 设置。如果未明确设置，将生成一个包含以下值的 JSON 对象作为默认值。一个 llm JSON 对象包含以下属性：
- "model_name", string
  The chat model name. If not set, the user's default chat model will be used.
  聊天模型名称。如果未设置，将使用用户的默认聊天模型。
- "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.
  控制模型预测的随机性。较低的温度会导致更保守的响应，而较高的温度会产生更具创造性和多样性的响应。默认值为 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
  也称为“核采样”，此参数设置一个阈值来选择一个较小的词集进行采样。它专注于最可能的词，截断不太可能的词。默认值为 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.
  这会阻止模型重复相同的信息，通过惩罚在对话中已经出现过的词。默认值为 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.
  类似于存在惩罚，这减少了模型频繁重复相同词的倾向。默认值为 0.7 。
"prompt": (Body parameter), object
"prompt" : (主体参数), object
Instructions for the LLM to follow. If it is not explicitly set, a JSON object with the following values will be generated as the default. A prompt JSON object contains the following attributes:
LLM 需要遵循的指令。如果没有明确设置，将生成一个包含以下值的 JSON 对象作为默认值。 prompt JSON 对象包含以下属性：
- "similarity_threshold": float RAGFlow employs either a combination of weighted keyword similarity and weighted vector cosine similarity, or a combination of weighted keyword similarity and weighted reranking score during retrieval. This argument sets the threshold for similarities between the user query and chunks. If a similarity score falls below this threshold, the corresponding chunk will be excluded from the results. The default value is 0.2.
  "similarity_threshold" : float RAGFlow 在检索过程中采用加权关键词相似度和加权向量余弦相似度的组合，或采用加权关键词相似度和加权重排序分数的组合。该参数设置用户查询和片段之间的相似度阈值。如果相似度分数低于此阈值，则相应的片段将不会出现在结果中。默认值为 0.2 。
- "keywords_similarity_weight": float This argument sets the weight of keyword similarity in the hybrid similarity score with vector cosine similarity or reranking model similarity. By adjusting this weight, you can control the influence of keyword similarity in relation to other similarity measures. The default value is 0.7.
  "keywords_similarity_weight" : float 该参数设置在混合相似度分数（与向量余弦相似度或重排序模型相似度）中关键词相似度的权重。通过调整此权重，您可以控制关键词相似度相对于其他相似度指标的影响。默认值为 0.7 。
- "top_n": int This argument specifies the number of top chunks with similarity scores above the similarity_threshold that are fed to the LLM. The LLM will only access these 'top N' chunks. The default value is 6.
  "top_n" : int 该参数指定相似度分数高于 similarity_threshold 的顶部片段数量，这些片段将被输入到 LLM 中。LLM 将仅访问这些“前 N”片段。默认值为 6 。
- "variables": object[] This argument lists the variables to use in the 'System' field of Chat Configurations. Note that:
  "variables" : object[] 这个参数列出了要在聊天配置的“系统”字段中使用的变量。请注意：
  - "knowledge" is a reserved variable, which represents the retrieved chunks.
    "knowledge" 是一个保留变量，代表检索到的片段。
  - All the variables in 'System' should be curly bracketed.
    “系统”字段中的所有变量都应该用花括号括起来。
  - The default value is [{"key": "knowledge", "optional": true}].
    默认值是 [{"key": "knowledge", "optional": true}] 。
- "rerank_model": string If it is not specified, vector cosine similarity will be used; otherwise, reranking score will be used.
  "rerank_model" : string 如果未指定，将使用向量余弦相似度；否则，将使用重新排序分数。
- top_k: int Refers to the process of reordering or selecting the top-k items from a list or set based on a specific ranking criterion. Default to 1024.
  top_k : int 指根据特定排序标准对列表或集合进行重新排序或选择前 k 项的过程。默认值为 1024。
- "empty_response": string If nothing is retrieved in the dataset for the user's question, this will be used as the response. To allow the LLM to improvise when nothing is found, leave this blank.
  "empty_response" : string 如果在数据集中未检索到用户问题的答案，将使用此作为响应。为允许 LLM 在未找到内容时进行即兴发挥，请留空此字段。
- "opener": string The opening greeting for the user. Defaults to "Hi! I am your assistant, can I help you?".
  "opener" : string 用户的问候语。默认为 "Hi! I am your assistant, can I help you?" 。
- "show_quote: boolean Indicates whether the source of text should be displayed. Defaults to true.
  "show_quote : boolean 指示是否应显示文本来源。默认为 true 。
- "prompt": string The prompt content.
  "prompt" : string 提示内容。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": {
        "avatar": "",
        "create_date": "Thu, 24 Oct 2024 11:18:29 GMT",
        "create_time": 1729768709023,
        "dataset_ids": [
            "527fa74891e811ef9c650242ac120006"
        ],
        "description": "A helpful Assistant",
        "do_refer": "1",
        "id": "b1f2f15691f911ef81180242ac120003",
        "language": "English",
        "llm": {
            "frequency_penalty": 0.7,
            "model_name": "qwen-plus@Tongyi-Qianwen",
            "presence_penalty": 0.4,
            "temperature": 0.1,
            "top_p": 0.3
        },
        "name": "12234",
        "prompt": {
            "empty_response": "Sorry! No relevant content was found in the knowledge base!",
            "keywords_similarity_weight": 0.3,
            "opener": "Hi! I'm your assistant, what can I do for you?",
            "prompt": "You are an intelligent assistant. Please summarize the content of the knowledge base to answer the question. Please list the data in the knowledge base and answer in detail. When all knowledge base content is irrelevant to the question, your answer must include the sentence \"The answer you are looking for is not found in the knowledge base!\" Answers need to consider chat history.\n ",
            "rerank_model": "",
            "similarity_threshold": 0.2,
            "top_n": 6,
            "variables": [
                {
                    "key": "knowledge",
                    "optional": false
                }
            ]
        },
        "prompt_type": "simple",
        "status": "1",
        "tenant_id": "69736c5e723611efb51b0242ac120007",
        "top_k": 1024,
        "update_date": "Thu, 24 Oct 2024 11:18:29 GMT",
        "update_time": 1729768709023
    }
}

Failure: 失败：

{
    "code": 102,
    "message": "Duplicated chat name in creating dataset."
}

Update chat assistant 更新聊天助手

PUT /api/v1/chats/{chat_id}

Updates configurations for a specified chat assistant.
更新指定聊天助手的配置。

Request 请求

Method: PUT 方法：PUT
URL: /api/v1/chats/{chat_id}
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "name": string
- "avatar": string
- "dataset_ids": list[string]
- "llm": object
- "prompt": object

Request example 请求示例

curl --request PUT \
     --url http://{address}/api/v1/chats/{chat_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "name":"Test"
     }'

Parameters 参数

chat_id: (Path parameter) chat_id : (路径参数)
The ID of the chat assistant to update.
要更新的聊天助手的 ID。
"name": (Body parameter), string, Required
"name" : (请求体参数), string , 必填
The revised name of the chat assistant.
聊天助手的修订名称。
"avatar": (Body parameter), string
"avatar" : (主体参数), string
Base64 encoding of the avatar.
头像的 Base64 编码
"dataset_ids": (Body parameter), list[string]
"dataset_ids" : (主体参数), list[string]
The IDs of the associated datasets.
关联数据集的 ID。
"llm": (Body parameter), object
"llm" : (主体参数), object
The LLM settings for the chat assistant to create. If it is not explicitly set, a dictionary with the following values will be generated as the default. An llm object contains the following attributes:
用于创建聊天助手的 LLM 设置。如果未明确设置，将生成一个包含以下值的默认字典。 llm 对象包含以下属性：
- "model_name", string
  The chat model name. If not set, the user's default chat model will be used.
  聊天模型名称。如果未设置，将使用用户的默认聊天模型。
- "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.
  控制模型预测的随机性。较低的温度会导致更保守的响应，而较高的温度会产生更具创造性和多样性的响应。默认值为 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
  也称为“核采样”，此参数设置一个阈值来选择一个较小的词集进行采样。它专注于最可能的词，截断不太可能的词。默认值为 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.2.
  这会阻止模型重复相同的信息，通过惩罚在对话中已经出现过的词。默认值为 0.2 。
- "frequency penalty": float
  Similar to the presence penalty, this reduces the model’s tendency to repeat the same words frequently. Defaults to 0.7.
  类似于存在惩罚，这减少了模型频繁重复相同词的倾向。默认值为 0.7 。
"prompt": (Body parameter), object
"prompt" : (主体参数), object
Instructions for the LLM to follow. A prompt object contains the following attributes:
用于 LLM 遵循的指令。一个 prompt 对象包含以下属性：
- "similarity_threshold": float RAGFlow employs either a combination of weighted keyword similarity and weighted vector cosine similarity, or a combination of weighted keyword similarity and weighted rerank score during retrieval. This argument sets the threshold for similarities between the user query and chunks. If a similarity score falls below this threshold, the corresponding chunk will be excluded from the results. The default value is 0.2.
  "similarity_threshold" : float RAGFlow 采用加权关键词相似度和加权向量余弦相似度组合，或加权关键词相似度和加权重新排序分数组合进行检索。此参数设置用户查询与片段之间的相似度阈值。如果相似度分数低于此阈值，相应的片段将被排除在结果之外。默认值为 0.2 。
- "keywords_similarity_weight": float This argument sets the weight of keyword similarity in the hybrid similarity score with vector cosine similarity or reranking model similarity. By adjusting this weight, you can control the influence of keyword similarity in relation to other similarity measures. The default value is 0.7.
  "keywords_similarity_weight" : float 此参数设置关键词相似度在混合相似度分数（与向量余弦相似度或重新排序模型相似度）中的权重。通过调整此权重，您可以控制关键词相似度相对于其他相似度指标的影响。默认值为 0.7 。
- "top_n": int This argument specifies the number of top chunks with similarity scores above the similarity_threshold that are fed to the LLM. The LLM will only access these 'top N' chunks. The default value is 8.
  "top_n" : int 此参数指定相似度分数高于 similarity_threshold 的前 N 个片段数量，这些片段将被输入到 LLM 中。LLM 仅能访问这些“前 N”片段。默认值为 8 。
- "variables": object[] This argument lists the variables to use in the 'System' field of Chat Configurations. Note that:
  "variables" : object[] 此参数列出在 Chat 配置的“系统”字段中使用的变量。注意：
  - "knowledge" is a reserved variable, which represents the retrieved chunks.
    "knowledge" 是一个保留变量，代表检索到的片段。
  - All the variables in 'System' should be curly bracketed.
    'System' 中的所有变量都应该用花括号括起来。
  - The default value is [{"key": "knowledge", "optional": true}]
    默认值是 [{"key": "knowledge", "optional": true}]
- "rerank_model": string If it is not specified, vector cosine similarity will be used; otherwise, reranking score will be used.
  "rerank_model" : string 如果未指定，将使用向量余弦相似度；否则，将使用重排序分数。
- "empty_response": string If nothing is retrieved in the dataset for the user's question, this will be used as the response. To allow the LLM to improvise when nothing is found, leave this blank.
  "empty_response" : string 如果数据集中没有检索到与用户问题相关的结果，将使用此内容作为响应。若要允许 LLM 在未找到内容时进行即兴发挥，请留空此字段。
- "opener": string The opening greeting for the user. Defaults to "Hi! I am your assistant, can I help you?".
  "opener" : string 用户的问候语。默认为 "Hi! I am your assistant, can I help you?" 。
- "show_quote: boolean Indicates whether the source of text should be displayed. Defaults to true.
  "show_quote : boolean 指示是否显示文本来源。默认为 true 。
- "prompt": string The prompt content.
  "prompt" : string 提示内容。

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "Duplicated chat name in updating dataset."
}

Delete chat assistants 删除聊天助手

DELETE /api/v1/chats 删除 /api/v1/chats

Deletes chat assistants by ID.
通过 ID 删除聊天助手。

Request 请求

Method: DELETE 方法：DELETE
URL: /api/v1/chats
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "ids": list[string]

Request example 请求示例

curl --request DELETE \
     --url http://{address}/api/v1/chats \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "ids": ["test_1", "test_2"]
     }'

Request parameters 请求参数

"ids": (Body parameter), list[string]
"ids" : (主体参数), list[string]
The IDs of the chat assistants to delete. If it is not specified, all chat assistants in the system will be deleted.
要删除的聊天助手的 ID。如果未指定，系统中的所有聊天助手将被删除。

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "ids are required"
}

List chat assistants 列出聊天助手

GET /api/v1/chats?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={chat_name}&id={chat_id}

Lists chat assistants. 列出聊天助手。

Request 请求

Method: GET 方法：GET
URL: /api/v1/chats?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={chat_name}&id={chat_id}
Headers:
- 'Authorization: Bearer <YOUR_API_KEY>'

Request example 请求示例

curl --request GET \
     --url http://{address}/api/v1/chats?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={chat_name}&id={chat_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Request parameters 请求参数

page: (Filter parameter), integer
page : (过滤参数), integer
Specifies the page on which the chat assistants will be displayed. Defaults to 1.
指定聊天助手将显示的页面。默认为 1 。
page_size: (Filter parameter), integer
page_size : (过滤参数), integer
The number of chat assistants on each page. Defaults to 30.
每页聊天助手的数量。默认为 30 。
orderby: (Filter parameter), string
orderby : (过滤参数), string
The attribute by which the results are sorted. Available options:
用于排序结果的属性。可选选项：
- create_time (default) create_time (默认)
- update_time
desc: (Filter parameter), boolean
desc : (过滤参数), boolean
Indicates whether the retrieved chat assistants should be sorted in descending order. Defaults to true.
指示检索到的聊天助手是否应按降序排序。默认为 true 。
id: (Filter parameter), string
id : (过滤参数), string
The ID of the chat assistant to retrieve.
要检索的聊天助手的 ID。
name: (Filter parameter), string
name : (过滤参数), string
The name of the chat assistant to retrieve.
要检索的聊天助手的名称。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": [
        {
            "avatar": "",
            "create_date": "Fri, 18 Oct 2024 06:20:06 GMT",
            "create_time": 1729232406637,
            "description": "A helpful Assistant",
            "do_refer": "1",
            "id": "04d0d8e28d1911efa3630242ac120006",
            "dataset_ids": ["527fa74891e811ef9c650242ac120006"],
            "language": "English",
            "llm": {
                "frequency_penalty": 0.7,
                "model_name": "qwen-plus@Tongyi-Qianwen",
                "presence_penalty": 0.4,
                "temperature": 0.1,
                "top_p": 0.3
            },
            "name": "13243",
            "prompt": {
                "empty_response": "Sorry! No relevant content was found in the knowledge base!",
                "keywords_similarity_weight": 0.3,
                "opener": "Hi! I'm your assistant, what can I do for you?",
                "prompt": "You are an intelligent assistant. Please summarize the content of the knowledge base to answer the question. Please list the data in the knowledge base and answer in detail. When all knowledge base content is irrelevant to the question, your answer must include the sentence \"The answer you are looking for is not found in the knowledge base!\" Answers need to consider chat history.\n",
                "rerank_model": "",
                "similarity_threshold": 0.2,
                "top_n": 6,
                "variables": [
                    {
                        "key": "knowledge",
                        "optional": false
                    }
                ]
            },
            "prompt_type": "simple",
            "status": "1",
            "tenant_id": "69736c5e723611efb51b0242ac120007",
            "top_k": 1024,
            "update_date": "Fri, 18 Oct 2024 06:20:06 GMT",
            "update_time": 1729232406638
        }
    ]
}

Failure: 失败：

{
    "code": 102,
    "message": "The chat doesn't exist"
}

SESSION MANAGEMENT 会话管理

Create session with chat assistant
创建与聊天助手的会话

POST /api/v1/chats/{chat_id}/sessions

Creates a session with a chat assistant.
创建一个与聊天助手会话的会话。

Request 请求

Method: POST 方法：POST
URL: /api/v1/chats/{chat_id}/sessions
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "name": string
- "user_id": string (optional) "user_id" : string (可选)

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/chats/{chat_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "name": "new session"
     }'

Request parameters 请求参数

chat_id: (Path parameter) chat_id : (路径参数)
The ID of the associated chat assistant.
关联聊天助手的 ID。
"name": (Body parameter), string
"name" : (主体参数), string
The name of the chat session to create.
创建聊天会话的名称。
"user_id": (Body parameter), string
"user_id" : (主体参数), string
Optional user-defined ID.
可选的用户自定义 ID。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": {
        "chat_id": "2ca4b22e878011ef88fe0242ac120005",
        "create_date": "Fri, 11 Oct 2024 08:46:14 GMT",
        "create_time": 1728636374571,
        "id": "4606b4ec87ad11efbc4f0242ac120006",
        "messages": [
            {
                "content": "Hi! I am your assistant, can I help you?",
                "role": "assistant"
            }
        ],
        "name": "new session",
        "update_date": "Fri, 11 Oct 2024 08:46:14 GMT",
        "update_time": 1728636374571
    }
}

Failure: 失败：

{
    "code": 102,
    "message": "Name cannot be empty."
}

Update chat assistant's session
更新聊天助手的会话

PUT /api/v1/chats/{chat_id}/sessions/{session_id}

Updates a session of a specified chat assistant.
更新指定聊天助手的会话。

Request 请求

Method: PUT 方法：PUT
URL: /api/v1/chats/{chat_id}/sessions/{session_id}
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "name: string
- "user_id: string (optional) "user_id : string (可选)

Request example 请求示例

curl --request PUT \
     --url http://{address}/api/v1/chats/{chat_id}/sessions/{session_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "name": "<REVISED_SESSION_NAME_HERE>"
     }'

Request Parameter 请求参数

chat_id: (Path parameter) chat_id : (路径参数)
The ID of the associated chat assistant.
关联聊天助手的 ID。
session_id: (Path parameter) session_id : (路径参数)
The ID of the session to update.
要更新的会话的 ID。
"name": (Body Parameter), string
"name" : (请求体参数), string
The revised name of the session.
会话的修订名称。
"user_id": (Body parameter), string
"user_id" : (主体参数), string
Optional user-defined ID.
可选的用户自定义 ID。

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "Name cannot be empty."
}

List chat assistant's sessions
列出聊天助手的会话

GET /api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}

Lists sessions associated with a specified chat assistant.
列出与指定聊天助手关联的会话。

Request 请求

Method: GET 方法：GET
URL: /api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}&user_id={user_id}
Headers:
- 'Authorization: Bearer <YOUR_API_KEY>'

Request example 请求示例

curl --request GET \
     --url http://{address}/api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Request Parameters 请求参数

chat_id: (Path parameter) chat_id : (路径参数)
The ID of the associated chat assistant.
关联聊天助手的 ID。
page: (Filter parameter), integer
page : (过滤参数), integer
Specifies the page on which the sessions will be displayed. Defaults to 1.
指定会话将显示的页面。默认为 1 。
page_size: (Filter parameter), integer
page_size : (过滤参数), integer
The number of sessions on each page. Defaults to 30.
每页上的会话数量。默认为 30 。
orderby: (Filter parameter), string
orderby : (过滤参数), string
The field by which sessions should be sorted. Available options:
会话应按哪个字段排序。可用选项：
- create_time (default) create_time (默认)
- update_time
desc: (Filter parameter), boolean
desc : (过滤参数), boolean
Indicates whether the retrieved sessions should be sorted in descending order. Defaults to true.
指示检索到的会话是否应按降序排序。默认为 true 。
name: (Filter parameter) string
name : (过滤参数) string
The name of the chat session to retrieve.
要检索的聊天会话的名称。
id: (Filter parameter), string
id : (过滤参数), string
The ID of the chat session to retrieve.
要检索的聊天会话的 ID。
user_id: (Filter parameter), string
user_id : (过滤参数), string
The optional user-defined ID passed in when creating session.
创建会话时传递的可选用户定义 ID。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": [
        {
            "chat": "2ca4b22e878011ef88fe0242ac120005",
            "create_date": "Fri, 11 Oct 2024 08:46:43 GMT",
            "create_time": 1728636403974,
            "id": "578d541e87ad11ef96b90242ac120006",
            "messages": [
                {
                    "content": "Hi! I am your assistant, can I help you?",
                    "role": "assistant"
                }
            ],
            "name": "new session",
            "update_date": "Fri, 11 Oct 2024 08:46:43 GMT",
            "update_time": 1728636403974
        }
    ]
}

Failure: 失败：

{
    "code": 102,
    "message": "The session doesn't exist"
}

Delete chat assistant's sessions
删除聊天助手的会话

DELETE /api/v1/chats/{chat_id}/sessions 删除 /api/v1/chats/{chat_id}/sessions

Deletes sessions of a chat assistant by ID.
删除聊天助手的会话，通过 ID。

Request 请求

Method: DELETE 方法：DELETE
URL: /api/v1/chats/{chat_id}/sessions
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "ids": list[string]

Request example 请求示例

curl --request DELETE \
     --url http://{address}/api/v1/chats/{chat_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "ids": ["test_1", "test_2"]
     }'

Request Parameters 请求参数

chat_id: (Path parameter) chat_id : (路径参数)
The ID of the associated chat assistant.
关联聊天助手的 ID。
"ids": (Body Parameter), list[string]
"ids" : (主体参数), list[string]
The IDs of the sessions to delete. If it is not specified, all sessions associated with the specified chat assistant will be deleted.
要删除的会话的 ID。如果没有指定，将删除与指定聊天助手关联的所有会话。

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "The chat doesn't own the session"
}

Converse with chat assistant
与聊天助手交谈

POST /api/v1/chats/{chat_id}/completions

Asks a specified chat assistant a question to start an AI-powered conversation.
向指定的聊天助手提问，以开始人工智能驱动的对话。

:::tip NOTE :::tip 注意

In streaming mode, not all responses include a reference, as this depends on the system's judgement.
在流式模式下，并非所有回复都包含引用，因为这取决于系统的判断。
In streaming mode, the last message is an empty message:
在流式模式下，最后一条消息是一个空消息：
```
data:
{
  "code": 0,
  "data": true
}
```

:::

Request 请求

Method: POST 方法：POST
URL: /api/v1/chats/{chat_id}/completions
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "question": string
- "stream": boolean
- "session_id": string (optional) "session_id" : string (可选)
- "user_id: string (optional) "user_id : string (可选)

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/chats/{chat_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
     {
     }'

curl --request POST \
     --url http://{address}/api/v1/chats/{chat_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
     {
          "question": "Who are you",
          "stream": true,
          "session_id":"9fa7691cb85c11ef9c5f0242ac120005"
     }'

Request Parameters 请求参数

chat_id: (Path parameter) chat_id : (路径参数)
The ID of the associated chat assistant.
关联聊天助手的 ID。
"question": (Body Parameter), string, Required
"question" : (主体参数), string , 必填
The question to start an AI-powered conversation.
用于启动 AI 驱动对话的问题。
"stream": (Body Parameter), boolean
"stream" : (主体参数), boolean
Indicates whether to output responses in a streaming way:
指示是否以流式方式输出响应：
- true: Enable streaming (default).
  true ：启用流式（默认）。
- false: Disable streaming. false ：禁用流式。
"session_id": (Body Parameter) "session_id" ：（主体参数）
The ID of session. If it is not provided, a new session will be generated.
会话的 ID。如果未提供，将生成新的会话。
"user_id": (Body parameter), string
"user_id" : (主体参数), string
The optional user-defined ID. Valid only when no session_id is provided.
可选的用户定义 ID。仅在未提供 session_id 时有效。

Response 响应

Success without session_id: 没有 session_id 的成功：

data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "Hi! I'm your assistant, what can I do for you?",
        "reference": {},
        "audio_binary": null,
        "id": null,
        "session_id": "b01eed84b85611efa0e90242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": true
}

Success with session_id: 成功 session_id :

data:{
    "code": 0,
    "data": {
        "answer": "I am an intelligent assistant designed to help answer questions by summarizing content from a",
        "reference": {},
        "audio_binary": null,
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data:{
    "code": 0,
    "data": {
        "answer": "I am an intelligent assistant designed to help answer questions by summarizing content from a knowledge base. My responses are based on the information available in the knowledge base and",
        "reference": {},
        "audio_binary": null,
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data:{
    "code": 0,
    "data": {
        "answer": "I am an intelligent assistant designed to help answer questions by summarizing content from a knowledge base. My responses are based on the information available in the knowledge base and any relevant chat history.",
        "reference": {},
        "audio_binary": null,
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data:{
    "code": 0,
    "data": {
        "answer": "I am an intelligent assistant designed to help answer questions by summarizing content from a knowledge base ##0$$. My responses are based on the information available in the knowledge base and any relevant chat history.",
        "reference": {
            "total": 1,
            "chunks": [
                {
                    "id": "faf26c791128f2d5e821f822671063bd",
                    "content": "xxxxxxxx",
                    "document_id": "dd58f58e888511ef89c90242ac120006",
                    "document_name": "1.txt",
                    "dataset_id": "8e83e57a884611ef9d760242ac120006",
                    "image_id": "",
                    "similarity": 0.7,
                    "vector_similarity": 0.0,
                    "term_similarity": 1.0,
                    "positions": [
                        ""
                    ]
                }
            ],
            "doc_aggs": [
                {
                    "doc_name": "1.txt",
                    "doc_id": "dd58f58e888511ef89c90242ac120006",
                    "count": 1
                }
            ]
        },
        "prompt": "xxxxxxxxxxx",
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data:{
    "code": 0,
    "data": true
}

Failure: 失败：

{
    "code": 102,
    "message": "Please input your question."
}

Create session with agent
创建代理会话

POST /api/v1/agents/{agent_id}/sessions

Creates a session with an agent.
创建一个与代理会话。

Request 请求

Method: POST 方法：POST
URL: /api/v1/agents/{agent_id}/sessions?user_id={user_id}
Headers:
- 'content-Type: application/json' or 'multipart/form-data'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- the required parameters:str
  必要的参数： str
- other parameters: The parameters specified in the Begin component.
  其他参数：Begin 组件中指定的参数。

Request example 请求示例

If the Begin component in your agent does not take required parameters:
如果您的代理中的 Begin 组件不接收必要的参数：

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     }'

If the Begin component in your agent takes required parameters:
如果您的代理中的 Begin 组件需要参数：

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
            "lang":"Japanese",
            "file":"Who are you"
     }'

If the Begin component in your agent takes required file parameters:
如果您的代理中的 Begin 组件需要文件参数：

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/sessions?user_id={user_id} \
     --header 'Content-Type: multipart/form-data' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --form '<FILE_KEY>=@./test1.png'

Request parameters 请求参数

agent_id: (Path parameter) agent_id : (路径参数)
The ID of the associated agent.
关联代理的 ID。
user_id: (Filter parameter) The optional user-defined ID for parsing docs (especially images) when creating a session while uploading files.
user_id : (过滤参数) 创建会话上传文件时，解析文档（尤其是图像）的可选用户定义 ID。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": {
        "agent_id": "b4a39922b76611efaa1a0242ac120006",
        "dsl": {
            "answer": [],
            "components": {
                "Answer:GreenReadersDrum": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Answer",
                        "inputs": [],
                        "output": null,
                        "params": {}
                    },
                    "upstream": []
                },
                "begin": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Begin",
                        "inputs": [],
                        "output": {},
                        "params": {}
                    },
                    "upstream": []
                }
            },
            "embed_id": "",
            "graph": {
                "edges": [],
                "nodes": [
                    {
                        "data": {
                            "label": "Begin",
                            "name": "begin"
                        },
                        "dragging": false,
                        "height": 44,
                        "id": "begin",
                        "position": {
                            "x": 53.25688640427177,
                            "y": 198.37155679786412
                        },
                        "positionAbsolute": {
                            "x": 53.25688640427177,
                            "y": 198.37155679786412
                        },
                        "selected": false,
                        "sourcePosition": "left",
                        "targetPosition": "right",
                        "type": "beginNode",
                        "width": 200
                    },
                    {
                        "data": {
                            "form": {},
                            "label": "Answer",
                            "name": "dialog_0"
                        },
                        "dragging": false,
                        "height": 44,
                        "id": "Answer:GreenReadersDrum",
                        "position": {
                            "x": 360.43473114516974,
                            "y": 207.29298425089348
                        },
                        "positionAbsolute": {
                            "x": 360.43473114516974,
                            "y": 207.29298425089348
                        },
                        "selected": false,
                        "sourcePosition": "right",
                        "targetPosition": "left",
                        "type": "logicNode",
                        "width": 200
                    }
                ]
            },
            "history": [],
            "messages": [],
            "path": [
                [
                    "begin"
                ],
                []
            ],
            "reference": []
        },
        "id": "2581031eb7a311efb5200242ac120005",
        "message": [
            {
                "content": "Hi! I'm your smart assistant. What can I do for you?",
                "role": "assistant"
            }
        ],
        "source": "agent",
        "user_id": "69736c5e723611efb51b0242ac120007"
    }
}

Failure: 失败：

{
    "code": 102,
    "message": "Agent not found."
}

Converse with agent 与代理交谈

POST /api/v1/agents/{agent_id}/completions

Asks a specified agent a question to start an AI-powered conversation.
向指定的代理提问以启动人工智能驱动的对话。

:::tip NOTE :::tip 注意

In streaming mode, not all responses include a reference, as this depends on the system's judgement.
在流式模式下，并非所有回复都包含引用，因为这取决于系统的判断。
In streaming mode, the last message is an empty message:
在流式模式下，最后一条消息是一个空消息：
```
data:
{
  "code": 0,
  "data": true
}
```

:::

Request 请求

Method: POST 方法：POST
URL: /api/v1/agents/{agent_id}/completions
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "question": string
- "stream": boolean
- "session_id": string
- "user_id": string(optional) "user_id" : string (可选)
- "sync_dsl": boolean (optional) "sync_dsl" : boolean (可选)
- other parameters: string 其他参数： string

:::info IMPORTANT You can include custom parameters in the request body, but first ensure they are defined in the Begin agent component. :::
:::info 重要您可以在请求体中包含自定义参数，但首先需确保它们已在 Begin agent 组件中定义。 :::

Request example 请求示例

If the Begin component does not take parameters, the following code will create a session.
如果 Begin 组件不带参数，以下代码将创建一个会话。

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
     {
     }'

If the Begin component takes parameters, the following code will create a session.

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
     {
          "lang":"English",
          "file":"How is the weather tomorrow?"
     }'

The following code will execute the completion process
以下代码将执行完成过程

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
     {
          "question": "Hello",
          "stream": true,
          "session_id": "cb2f385cb86211efa36e0242ac120005"
     }'

Request Parameters 请求参数

agent_id: (Path parameter), string
agent_id : (路径参数), string
The ID of the associated agent.
关联代理的 ID。
"question": (Body Parameter), string, Required
"question" : (主体参数), string , 必填
The question to start an AI-powered conversation.
用于启动 AI 驱动对话的问题。
"stream": (Body Parameter), boolean
"stream" : (主体参数), boolean
Indicates whether to output responses in a streaming way:
指示是否以流式方式输出响应：
- true: Enable streaming (default).
  true ：启用流式（默认）。
- false: Disable streaming. false ：禁用流式。
"session_id": (Body Parameter) "session_id" ：（主体参数）
The ID of the session. If it is not provided, a new session will be generated.
会话的 ID。如果未提供，将生成新的会话。
"user_id": (Body parameter), string
"user_id" : (主体参数), string
The optional user-defined ID. Valid only when no session_id is provided.
可选的用户定义 ID。仅在未提供 session_id 时有效。
"sync_dsl": (Body parameter), boolean Whether to synchronize the changes to existing sessions when an agent is modified, defaults to false.
"sync_dsl" : (请求体参数)， boolean 当代理被修改时，是否将更改同步到现有会话，默认为 false 。
Other parameters: (Body Parameter)
其他参数： (请求体参数)
Parameters specified in the Begin component.
Begin 组件中指定的参数。

Response 响应

success without session_id provided and with no parameters specified in the Begin component:
未提供 session_id 且 Begin 组件中未指定参数时成功：

data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "Hi! I'm your smart assistant. What can I do for you?",
        "reference": {},
        "id": "31e6091d-88d4-441b-ac65-eae1c055be7b",
        "session_id": "2987ad3eb85f11efb2a70242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": true
}

Success without session_id provided and with parameters specified in the Begin component:
未提供 session_id 且已指定 Begin 组件中的参数时成功：

data:{
    "code": 0,
    "message": "",
    "data": {
        "session_id": "eacb36a0bdff11ef97120242ac120006",
        "answer": "",
        "reference": [],
        "param": [
            {
                "key": "lang",
                "name": "Target Language",
                "optional": false,
                "type": "line",
                "value": "English"
            },
            {
                "key": "file",
                "name": "Files",
                "optional": false,
                "type": "file",
                "value": "How is the weather tomorrow?"
            },
            {
                "key": "hhyt",
                "name": "hhty",
                "optional": true,
                "type": "line"
            }
        ]
    }
}
data:

Success with parameters specified in the Begin component:
在 Begin 组件中指定的参数成功：

data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the weather",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the weather tomorrow",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the weather tomorrow?",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the weather tomorrow?",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": true
}

Failure: 失败：

{
    "code": 102,
    "message": "`question` is required."
}

List agent sessions 列出代理会话

GET /api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}&user_id={user_id}&dsl={dsl}

Lists sessions associated with a specified agent.
列出与指定代理关联的会话。

Request 请求

Method: GET 方法：GET
URL: /api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}
Headers:
- 'Authorization: Bearer <YOUR_API_KEY>'

Request example 请求示例

curl --request GET \
     --url http://{address}/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}&user_id={user_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Request Parameters 请求参数

agent_id: (Path parameter) agent_id : (路径参数)
The ID of the associated agent.
关联代理的 ID。
page: (Filter parameter), integer
page : (过滤参数), integer
Specifies the page on which the sessions will be displayed. Defaults to 1.
指定会话将显示在哪个页面上。默认值为 1 。
page_size: (Filter parameter), integer
page_size : (过滤参数), integer
The number of sessions on each page. Defaults to 30.
每页上的会话数量。默认为 30 。
orderby: (Filter parameter), string
orderby : (过滤参数), string
The field by which sessions should be sorted. Available options:
用于排序会话的字段。可用选项：
- create_time (default) create_time (默认)
- update_time
desc: (Filter parameter), boolean
desc : (过滤参数), boolean
Indicates whether the retrieved sessions should be sorted in descending order. Defaults to true.
指示检索到的会话是否按降序排序。默认为 true 。
id: (Filter parameter), string
id : (过滤参数), string
The ID of the agent session to retrieve.
要检索的代理会话的 ID。
user_id: (Filter parameter), string
user_id : (过滤参数), string
The optional user-defined ID passed in when creating session.
创建会话时传递的可选用户定义 ID。
dsl: (Filter parameter), boolean
dsl : (过滤参数), boolean
Indicates whether to include the dsl field of the sessions in the response. Defaults to true.
指示是否在响应中包含会话的 dsl 字段。默认值为 true 。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": [{
        "agent_id": "e9e2b9c2b2f911ef801d0242ac120006",
        "dsl": {
            "answer": [],
            "components": {
                "Answer:OrangeTermsBurn": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Answer",
                        "params": {}
                    },
                    "upstream": []
                },
                "Generate:SocialYearsRemain": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Generate",
                        "params": {
                            "cite": true,
                            "frequency_penalty": 0.7,
                            "llm_id": "gpt-4o___OpenAI-API@OpenAI-API-Compatible",
                            "message_history_window_size": 12,
                            "parameters": [],
                            "presence_penalty": 0.4,
                            "prompt": "Please summarize the following paragraph. Pay attention to the numbers and do not make things up. The paragraph is as follows:\n{input}\nThis is what you need to summarize.",
                            "temperature": 0.1,
                            "top_p": 0.3
                        }
                    },
                    "upstream": []
                },
                "begin": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Begin",
                        "params": {}
                    },
                    "upstream": []
                }
            },
            "graph": {
                "edges": [],
                "nodes": [
                    {
                        "data": {
                            "label": "Begin",
                            "name": "begin"
                        },
                        "height": 44,
                        "id": "begin",
                        "position": {
                            "x": 50,
                            "y": 200
                        },
                        "sourcePosition": "left",
                        "targetPosition": "right",
                        "type": "beginNode",
                        "width": 200
                    },
                    {
                        "data": {
                            "form": {
                                "cite": true,
                                "frequencyPenaltyEnabled": true,
                                "frequency_penalty": 0.7,
                                "llm_id": "gpt-4o___OpenAI-API@OpenAI-API-Compatible",
                                "maxTokensEnabled": true,
                                "message_history_window_size": 12,
                                "parameters": [],
                                "presencePenaltyEnabled": true,
                                "presence_penalty": 0.4,
                                "prompt": "Please summarize the following paragraph. Pay attention to the numbers and do not make things up. The paragraph is as follows:\n{input}\nThis is what you need to summarize.",
                                "temperature": 0.1,
                                "temperatureEnabled": true,
                                "topPEnabled": true,
                                "top_p": 0.3
                            },
                            "label": "Generate",
                            "name": "Generate Answer_0"
                        },
                        "dragging": false,
                        "height": 105,
                        "id": "Generate:SocialYearsRemain",
                        "position": {
                            "x": 561.3457829707513,
                            "y": 178.7211182312641
                        },
                        "positionAbsolute": {
                            "x": 561.3457829707513,
                            "y": 178.7211182312641
                        },
                        "selected": true,
                        "sourcePosition": "right",
                        "targetPosition": "left",
                        "type": "generateNode",
                        "width": 200
                    },
                    {
                        "data": {
                            "form": {},
                            "label": "Answer",
                            "name": "Dialogue_0"
                        },
                        "height": 44,
                        "id": "Answer:OrangeTermsBurn",
                        "position": {
                            "x": 317.2368194777658,
                            "y": 218.30635555445093
                        },
                        "sourcePosition": "right",
                        "targetPosition": "left",
                        "type": "logicNode",
                        "width": 200
                    }
                ]
            },
            "history": [],
            "messages": [],
            "path": [],
            "reference": []
        },
        "id": "792dde22b2fa11ef97550242ac120006",
        "message": [
            {
                "content": "Hi! I'm your smart assistant. What can I do for you?",
                "role": "assistant"
            }
        ],
        "source": "agent",
        "user_id": ""
    }]
}

Failure: 失败：

{
    "code": 102,
    "message": "You don't own the agent ccd2f856b12311ef94ca0242ac1200052."
}

Delete agent's sessions 删除代理的会话

DELETE /api/v1/agents/{agent_id}/sessions 删除 /api/v1/agents/{agent_id}/sessions

Deletes sessions of a agent by ID.
删除指定 ID 的代理会话。

Request 请求

Method: DELETE 方法：DELETE
URL: /api/v1/agents/{agent_id}/sessions
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "ids": list[string]

Request example 请求示例

curl --request DELETE \
     --url http://{address}/api/v1/agents/{agent_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "ids": ["test_1", "test_2"]
     }'

Request Parameters 请求参数

agent_id: (Path parameter) agent_id : (路径参数)
The ID of the associated agent.
关联代理的 ID。
"ids": (Body Parameter), list[string]
"ids" : (主体参数), list[string]
The IDs of the sessions to delete. If it is not specified, all sessions associated with the specified agent will be deleted.
要删除的会话的 ID。如果未指定，将删除与指定代理关联的所有会话。

Response 响应

Success: 成功：

{
    "code": 0
}

Failure: 失败：

{
    "code": 102,
    "message": "The agent doesn't own the session cbd31e52f73911ef93b232903b842af6"
}

POST /v1/sessions/related_questions

Generates five to ten alternative question strings from the user's original query to retrieve more relevant search results.
从用户的原始查询中生成五到十个替代问题字符串，以检索更相关的搜索结果。

This operation requires a Bearer Login Token, which typically expires with in 24 hours. You can find the it in the Request Headers in your browser easily.
此操作需要一个 Bearer Login Token ，通常在 24 小时内过期。您可以在浏览器的请求头中轻松找到它。

:::tip NOTE The chat model autonomously determines the number of questions to generate based on the instruction, typically between five and ten. :::
:::tip 注意聊天模型会根据指令自主决定生成问题的数量，通常在五到十个之间。 :::

Request 请求

Method: POST 方法：POST
URL: /v1/sessions/related_questions
Headers:
- 'content-Type: application/json'
- 'Authorization: Bearer <YOUR_LOGIN_TOKEN>'
Body:
- "question": string

Request example 请求示例

curl --request POST \
     --url http://{address}/v1/sessions/related_questions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_LOGIN_TOKEN>' \
     --data '
     {
          "question": "What are the key advantages of Neovim over Vim?"
     }'

Request Parameters 请求参数

"question": (Body Parameter), string The original user question.
"question" : (主体参数), string 原始用户问题。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": [
        "What makes Neovim superior to Vim in terms of features?",
        "How do the benefits of Neovim compare to those of Vim?",
        "What advantages does Neovim offer that are not present in Vim?",
        "In what ways does Neovim outperform Vim in functionality?",
        "What are the most significant improvements in Neovim compared to Vim?",
        "What unique advantages does Neovim bring to the table over Vim?",
        "How does the user experience in Neovim differ from Vim in terms of benefits?",
        "What are the top reasons to switch from Vim to Neovim?",
        "What features of Neovim are considered more advanced than those in Vim?"
    ],
    "message": "success"
}

Failure: 失败：

{
    "code": 401,
    "data": null,
    "message": "<Unauthorized '401: Unauthorized'>"
}

AGENT MANAGEMENT 代理管理

List agents 列出代理

GET /api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={agent_name}&id={agent_id}

Lists agents. 列出代理。

Request 请求

Method: GET 方法：GET
URL: /api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={agent_name}&id={agent_id}
Headers:
- 'Authorization: Bearer <YOUR_API_KEY>'

Request example 请求示例

curl --request GET \
     --url http://{address}/api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={agent_name}&id={agent_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Request parameters 请求参数

page: (Filter parameter), integer
page : (过滤参数), integer
Specifies the page on which the agents will be displayed. Defaults to 1.
指定代理将显示的页面。默认为 1 。
page_size: (Filter parameter), integer
page_size : (过滤参数), integer
The number of agents on each page. Defaults to 30.
每页上的代理数量。默认为 30 。
orderby: (Filter parameter), string
orderby : (过滤参数), string
The attribute by which the results are sorted. Available options:
用于排序结果的属性。可选选项：
- create_time (default) create_time (默认)
- update_time
desc: (Filter parameter), boolean
desc : (过滤参数), boolean
Indicates whether the retrieved agents should be sorted in descending order. Defaults to true.
指示检索到的代理是否按降序排序。默认值为 true 。
id: (Filter parameter), string
id : (过滤参数), string
The ID of the agent to retrieve.
要检索的代理的 ID。
name: (Filter parameter), string
name : (过滤参数), string
The name of the agent to retrieve.
要检索的代理的名称。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": [
        {
            "avatar": null,
            "canvas_type": null,
            "create_date": "Thu, 05 Dec 2024 19:10:36 GMT",
            "create_time": 1733397036424,
            "description": null,
            "dsl": {
                "answer": [],
                "components": {
                    "begin": {
                        "downstream": [],
                        "obj": {
                            "component_name": "Begin",
                            "params": {}
                        },
                        "upstream": []
                    }
                },
                "graph": {
                    "edges": [],
                    "nodes": [
                        {
                            "data": {
                                "label": "Begin",
                                "name": "begin"
                            },
                            "height": 44,
                            "id": "begin",
                            "position": {
                                "x": 50,
                                "y": 200
                            },
                            "sourcePosition": "left",
                            "targetPosition": "right",
                            "type": "beginNode",
                            "width": 200
                        }
                    ]
                },
                "history": [],
                "messages": [],
                "path": [],
                "reference": []
            },
            "id": "8d9ca0e2b2f911ef9ca20242ac120006",
            "title": "123465",
            "update_date": "Thu, 05 Dec 2024 19:10:56 GMT",
            "update_time": 1733397056801,
            "user_id": "69736c5e723611efb51b0242ac120007"
        }
    ]
}

Failure: 失败：

{
    "code": 102,
    "message": "The agent doesn't exist."
}

Create agent 创建代理

POST /api/v1/agents

Create an agent. 创建一个代理。

Request 请求

Method: POST 方法：POST
URL: /api/v1/agents
Headers:
- 'Content-Type: application/json
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "title": string
- "description": string
- "dsl": object

Request example 请求示例

curl --request POST \
     --url http://{address}/api/v1/agents \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
         "title": "Test Agent",
         "description": "A test agent",
         "dsl": {
           // ... Canvas DSL here ...
         }
     }'

Request parameters 请求参数

title: (Body parameter), string, Required
title : (请求体参数), string , 必填
The title of the agent.
代理的标题。
description: (Body parameter), string
description : (主体参数), string
The description of the agent. Defaults to None.
代理的描述。默认为 None 。
dsl: (Body parameter), object, Required
dsl : (请求体参数), object , 必填
The canvas DSL object of the agent.
代理的画布 DSL 对象。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": true,
    "message": "success"
}

Failure: 失败：

{
    "code": 102,
    "message": "Agent with title test already exists."
}

Update agent 更新代理

PUT /api/v1/agents/{agent_id}

Update an agent by id.
通过 ID 更新代理。

Request 请求

Method: PUT 方法：PUT
URL: /api/v1/agents/{agent_id}
Headers:
- 'Content-Type: application/json
- 'Authorization: Bearer <YOUR_API_KEY>'
Body:
- "title": string
- "description": string
- "dsl": object

Request example 请求示例

curl --request PUT \
     --url http://{address}/api/v1/agents/58af890a2a8911f0a71a11b922ed82d6 \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
         "title": "Test Agent",
         "description": "A test agent",
         "dsl": {
           // ... Canvas DSL here ...
         }
     }'

Request parameters 请求参数

agent_id: (Path parameter), string
agent_id : (路径参数), string
The id of the agent to be updated.
要更新的代理的 ID。
title: (Body parameter), string
title : (主体参数), string
The title of the agent.
代理的标题。
description: (Body parameter), string
description : (主体参数), string
The description of the agent.
代理的描述。
dsl: (Body parameter), object
dsl : (主体参数), object
The canvas DSL object of the agent.
代理的画布 DSL 对象。

Only specify the parameter you want to change in the request body. If a parameter does not exist or is None, it won't be updated.
仅指定您想要更改的参数在请求体中。如果参数不存在或为 None ，则不会被更新。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": true,
    "message": "success"
}

Failure: 失败：

{
    "code": 103,
    "message": "Only owner of canvas authorized for this operation."
}

Delete agent 删除代理

DELETE /api/v1/agents/{agent_id} 删除 /api/v1/agents/{agent_id}

Delete an agent by id.
通过 id 删除一个代理。

Request 请求

Method: DELETE 方法：DELETE
URL: /api/v1/agents/{agent_id}
Headers:
- 'Content-Type: application/json
- 'Authorization: Bearer <YOUR_API_KEY>'

Request example 请求示例

curl --request DELETE \
     --url http://{address}/api/v1/agents/58af890a2a8911f0a71a11b922ed82d6 \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{}'

Request parameters 请求参数

agent_id: (Path parameter), string
agent_id : (路径参数), string
The id of the agent to be deleted.
要删除的代理的 id。

Response 响应

Success: 成功：

{
    "code": 0,
    "data": true,
    "message": "success"
}

Failure: 失败：

{
    "code": 103,
    "message": "Only owner of canvas authorized for this operation."
}

Langfuse

跟踪、评估、提示管理和指标，以调试和改进您的 LLM 应用程序。

sidebar_position: 4 slug: /http_api_reference

HTTP API

ERROR CODES 错误代码

OpenAI-Compatible API OpenAI 兼容 API

Create chat completion 创建聊天完成

Request 请求

Request example 请求示例

Request Parameters 请求参数

Response 响应

Create agent completion 创建代理完成

Request 请求

Request example 请求示例

Request Parameters 请求参数

Response 响应

DATASET MANAGEMENT 数据集管理

Create dataset 创建数据集

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

Delete datasets 删除数据集

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

Update dataset 更新数据集

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

List datasets 列出数据集

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

FILE MANAGEMENT WITHIN DATASET数据集中的文件管理

Upload documents 上传文档

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

Update document 更新文档

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

Download document 下载文档

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

List documents 列出文档

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

Delete documents 删除文档

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

Parse documents 解析文档

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

Stop parsing documents 停止解析文档

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

CHUNK MANAGEMENT WITHIN DATASET数据集中的块管理

Add chunk 添加片段

Request 请求

Request example 请求示例

Request parameters 请求参数

Response 响应

List chunks 列出片段

Request 请求

Request example 请求示例

FILE MANAGEMENT WITHIN DATASET
数据集中的文件管理

CHUNK MANAGEMENT WITHIN DATASET
数据集中的块管理

CHAT ASSISTANT MANAGEMENT
聊天助手管理

Create session with chat assistant
创建与聊天助手的会话

Update chat assistant's session
更新聊天助手的会话

List chat assistant's sessions
列出聊天助手的会话

Delete chat assistant's sessions
删除聊天助手的会话

Converse with chat assistant
与聊天助手交谈

Create session with agent
创建代理会话