Skip to main content
Version: DEV

HTTP API

RAGFlow RESTful API 的完整参考。在继续之前，请确保您已准备好 RAGFlow API 密钥进行身份验证。

错误代码​

代码消息描述
400错误请求无效的请求参数
401未授权未授权访问
403禁止访问被拒绝
404未找到资源未找到
500内部服务器错误服务器内部错误
1001无效的块 ID无效的块 ID
1002块更新失败块更新失败

OpenAI 兼容 API​

创建聊天完成​

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

为给定的聊天对话创建模型响应。

此 API 遵循与 OpenAI API 相同的请求和响应格式。它允许您以类似于与 OpenAI API 交互的方式与模型交互。

请求​

  • 方法：POST
  • URL：/api/v1/chats_openai/{chat_id}/chat/completions
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "model"：string
    • "messages"：object list
    • "stream"：boolean
请求示例​
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
      }'
请求参数​

  • model（请求体参数）string，必需
    用于生成响应的模型。服务器会自动解析此参数，因此您可以暂时将其设置为任何值。

  • messages（请求体参数）list[object]，必需
    用于生成响应的历史聊天消息列表。此列表必须包含至少一条 user 角色的消息。

  • stream（请求体参数）boolean
    是否以流的形式接收响应。如果您希望一次性接收整个响应而不是流式响应，请将此参数显式设置为 false。

响应​

流式响应：

data:{
    "id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728",
    "choices": [
        {
            "delta": {
                "content": "Hello! It seems like you're just greeting me. If you have a specific",
                "role": "assistant",
                "function_call": null,
                "tool_calls": null,
                "reasoning_content": null
            },
            "finish_reason": null,
            "index": 0,
            "logprobs": null
        }
    ],
    "created": 1755084508,
    "model": "model",
    "object": "chat.completion.chunk",
    "system_fingerprint": "",
    "usage": null
}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " question or need information, feel free to ask, and I'll do my best", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " to assist you based on the knowledge base provided.", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": null, "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": "stop", "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": {"prompt_tokens": 5, "completion_tokens": 188, "total_tokens": 193}}

data:[DONE]

非流式响应：

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "Hello! I'm your smart assistant. What can I do for you?",
                "role": "assistant"
            }
        }
    ],
    "created": 1755084403,
    "id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728",
    "model": "model",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 55,
        "completion_tokens_details": {
            "accepted_prediction_tokens": 55,
            "reasoning_tokens": 5,
            "rejected_prediction_tokens": 0
        },
        "prompt_tokens": 5,
        "total_tokens": 60
    }
}

失败响应：

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

创建代理完成​

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

为给定的聊天对话创建模型响应。

此 API 遵循与 OpenAI API 相同的请求和响应格式。它允许您以类似于与 OpenAI API 交互的方式与模型交互。

请求​

  • 方法：POST
  • URL：/api/v1/agents_openai/{agent_id}/chat/completions
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "model"：string
    • "messages"：object list
    • "stream"：boolean
请求示例​
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
      }'
请求参数​

  • model（请求体参数）string，必需
    用于生成响应的模型。服务器会自动解析此参数，因此您可以暂时将其设置为任何值。

  • messages（请求体参数）list[object]，必需
    用于生成响应的历史聊天消息列表。此列表必须包含至少一条 user 角色的消息。

  • stream（请求体参数）boolean
    是否以流的形式接收响应。如果您希望一次性接收整个响应而不是流式响应，请将此参数显式设置为 false。

  • session_id（请求体参数）string
    代理会话 ID。

Response​

Stream:

...

data: {
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "object": "chat.completion.chunk",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "choices": [
        {
            "delta": {
                "content": " terminal"
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: {
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "object": "chat.completion.chunk",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "choices": [
        {
            "delta": {
                "content": "."
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: {
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "object": "chat.completion.chunk",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "choices": [
        {
            "delta": {
                "content": "",
                "reference": {
                    "chunks": {
                        "20": {
                            "id": "4b8935ac0a22deb1",
                            "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.",
                            "document_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "document_name": "INSTALL22.md",
                            "dataset_id": "456ce60c5e1511f0907f09f583941b45",
                            "image_id": "",
                            "positions": [
                                [
                                    12,
                                    11,
                                    11,
                                    11,
                                    11
                                ]
                            ],
                            "url": null,
                            "similarity": 0.5697155305154673,
                            "vector_similarity": 0.7323851005515574,
                            "term_similarity": 0.5000000005,
                            "doc_type": ""
                        }
                    },
                    "doc_aggs": {
                        "INSTALL22.md": {
                            "doc_name": "INSTALL22.md",
                            "doc_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "count": 3
                        },
                        "INSTALL.md": {
                            "doc_name": "INSTALL.md",
                            "doc_id": "4bd7fdd85e1511f0907f09f583941b45",
                            "count": 2
                        },
                        "INSTALL(1).md": {
                            "doc_name": "INSTALL(1).md",
                            "doc_id": "4bdfb42e5e1511f0907f09f583941b45",
                            "count": 2
                        },
                        "INSTALL3.md": {
                            "doc_name": "INSTALL3.md",
                            "doc_id": "4bdab5825e1511f0907f09f583941b45",
                            "count": 1
                        }
                    }
                }
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: [DONE]

非流式：

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "\nTo install Neovim, the process varies depending on your operating system:\n\n### For Windows:\n1. **Download from GitHub**: \n   - Visit the [Neovim releases page](https://github.com/neovim/neovim/releases)\n   - Download the latest Windows installer (nvim-win64.msi)\n   - Run the installer and follow the prompts\n\n2. **Using winget** (Windows Package Manager):\n...",
                "reference": {
                    "chunks": {
                        "20": {
                            "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.",
                            "dataset_id": "456ce60c5e1511f0907f09f583941b45",
                            "doc_type": "",
                            "document_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "document_name": "INSTALL22.md",
                            "id": "4b8935ac0a22deb1",
                            "image_id": "",
                            "positions": [
                                [
                                    12,
                                    11,
                                    11,
                                    11,
                                    11
                                ]
                            ],
                            "similarity": 0.5697155305154673,
                            "term_similarity": 0.5000000005,
                            "url": null,
                            "vector_similarity": 0.7323851005515574
                        }
                    },
                    "doc_aggs": {
                        "INSTALL(1).md": {
                            "count": 2,
                            "doc_id": "4bdfb42e5e1511f0907f09f583941b45",
                            "doc_name": "INSTALL(1).md"
                        },
                        "INSTALL.md": {
                            "count": 2,
                            "doc_id": "4bd7fdd85e1511f0907f09f583941b45",
                            "doc_name": "INSTALL.md"
                        },
                        "INSTALL22.md": {
                            "count": 3,
                            "doc_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "doc_name": "INSTALL22.md"
                        },
                        "INSTALL3.md": {
                            "count": 1,
                            "doc_id": "4bdab5825e1511f0907f09f583941b45",
                            "doc_name": "INSTALL3.md"
                        }
                    }
                },
                "role": "assistant"
            }
        }
    ],
    "created": null,
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "object": "chat.completion",
    "param": null,
    "usage": {
        "completion_tokens": 415,
        "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
        },
        "prompt_tokens": 6,
        "total_tokens": 421
    }
}

Failure:

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

知识库管理​

创建知识库​

POST /api/v1/datasets

创建知识库。

请求​

  • 方法：POST
  • URL：/api/v1/datasets
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "name"：string
    • "avatar"：string
    • "description"：string
    • "embedding_model"：string
    • "permission"：string
    • "chunk_method"：string
    • "parser_config"：object
请求示例​
curl --request POST \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
      "name": "test_1"
      }'
请求参数​

  • "name"：（请求体参数），string，必需
    要创建的知识库的唯一名称。它必须符合以下要求：

    • 仅限基本多语言平面（BMP）
    • 最多 128 个字符
    • 不区分大小写

  • "avatar": (Body parameter), string
    Base64 encoding of the avatar.

    • Maximum 65535 characters

  • "description": (Body parameter), string
    A brief description of the dataset to create.

    • Maximum 65535 characters

  • "embedding_model": (Body parameter), string
    The name of the embedding model to use. For example: "BAAI/bge-large-zh-v1.5@BAAI"

    • Maximum 255 characters
    • Must follow model_name@model_factory format

  • "permission": (Body parameter), string
    Specifies who can access the dataset to create. Available options:

    • "me": (Default) Only you can manage the dataset.
    • "team": All team members can manage the dataset.

  • "chunk_method": (Body parameter), enum<string>
    The chunking method of the dataset to create. Available options:

    • "naive": General (default)
    • "book": Book
    • "email": Email
    • "laws": Laws
    • "manual": Manual
    • "one": One
    • "paper": Paper
    • "picture": Picture
    • "presentation": Presentation
    • "qa": Q&A
    • "table": Table
    • "tag": Tag

  • "parser_config": (Body parameter), object
    The configuration settings for the dataset parser. The attributes in this JSON object vary with the selected "chunk_method":

    • If "chunk_method" is "naive", the "parser_config" object contains the following attributes:
      • "auto_keywords": int
        • Defaults to 0
        • Minimum: 0
        • Maximum: 32
      • "auto_questions": int
        • Defaults to 0
        • Minimum: 0
        • Maximum: 10
      • "chunk_token_num": int
        • Defaults to 512
        • Minimum: 1
        • Maximum: 2048
      • "delimiter": string
        • Defaults to "\n".
      • "html4excel": bool Indicates whether to convert Excel documents into HTML format.
        • Defaults to false
      • "layout_recognize": string
        • Defaults to DeepDOC
      • "tag_kb_ids": array<string> refer to Use tag set
        • Must include a list of dataset IDs, where each dataset is parsed using the ​​Tag Chunking Method
      • "task_page_size": int For PDF only.
        • Defaults to 12
        • Minimum: 1
      • "raptor": object RAPTOR-specific settings.
        • Defaults to: {"use_raptor": false}
      • "graphrag": object GRAPHRAG-specific settings.
        • Defaults to: {"use_graphrag": false}
    • If "chunk_method" is "qa", "manuel", "paper", "book", "laws", or "presentation", the "parser_config" object contains the following attribute:
      • "raptor": object RAPTOR-specific settings.
        • Defaults to: {"use_raptor": false}.
    • If "chunk_method" is "table", "picture", "one", or "email", "parser_config" is an empty JSON object.

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 /api/v1/datasets

按 ID 删除知识库。

请求​

  • 方法：DELETE
  • URL：/api/v1/datasets
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
    • 请求体：
      • "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
    Specifies the datasets to delete:
    • If null, all datasets will be deleted.
    • If an array of IDs, only the specified datasets will be deleted.
    • If an empty array, no datasets will be deleted.

Response​

Success:

{
    "code": 0 
}

Failure:

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

更新知识库​

PUT /api/v1/datasets/{dataset_id}

更新指定知识库的配置。

请求​

  • 方法：PUT
  • URL：/api/v1/datasets/{dataset_id}
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "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)
    The ID of the dataset to update.
  • "name": (Body parameter), string
    The revised name of the dataset.
    • Basic Multilingual Plane (BMP) only
    • Maximum 128 characters
    • Case-insensitive
  • "avatar": (Body parameter), string
    The updated base64 encoding of the avatar.
    • Maximum 65535 characters
  • "embedding_model": (Body parameter), string
    The updated embedding model name.
    • Ensure that "chunk_count" is 0 before updating "embedding_model".
    • Maximum 255 characters
    • Must follow model_name@model_factory format
  • "permission": (Body parameter), string
    The updated dataset permission. Available options:
    • "me": (Default) Only you can manage the dataset.
    • "team": All team members can manage the dataset.
  • "pagerank": (Body parameter), int
    refer to Set page rank
    • Default: 0
    • Minimum: 0
    • Maximum: 100
  • "chunk_method": (Body parameter), enum<string>
    The chunking method for the dataset. Available options:
    • "naive": General (default)
    • "book": Book
    • "email": Email
    • "laws": Laws
    • "manual": Manual
    • "one": One
    • "paper": Paper
    • "picture": Picture
    • "presentation": Presentation
    • "qa": Q&A
    • "table": Table
    • "tag": Tag
  • "parser_config": (Body parameter), object
    The configuration settings for the dataset parser. The attributes in this JSON object vary with the selected "chunk_method":
    • If "chunk_method" is "naive", the "parser_config" object contains the following attributes:
      • "auto_keywords": int
        • Defaults to 0
        • Minimum: 0
        • Maximum: 32
      • "auto_questions": int
        • Defaults to 0
        • Minimum: 0
        • Maximum: 10
      • "chunk_token_num": int
        • Defaults to 512
        • Minimum: 1
        • Maximum: 2048
      • "delimiter": string
        • Defaults to "\n".
      • "html4excel": bool Indicates whether to convert Excel documents into HTML format.
        • Defaults to false
      • "layout_recognize": string
        • Defaults to DeepDOC
      • "tag_kb_ids": array<string> refer to Use tag set
        • Must include a list of dataset IDs, where each dataset is parsed using the ​​Tag Chunking Method
      • "task_page_size": int For PDF only.
        • Defaults to 12
        • Minimum: 1
      • "raptor": object RAPTOR-specific settings.
        • Defaults to: {"use_raptor": false}
      • "graphrag": object GRAPHRAG-specific settings.
        • Defaults to: {"use_graphrag": false}
    • If "chunk_method" is "qa", "manuel", "paper", "book", "laws", or "presentation", the "parser_config" object contains the following attribute:
      • "raptor": object RAPTOR-specific settings.
        • Defaults to: {"use_raptor": false}.
    • If "chunk_method" is "table", "picture", "one", or "email", "parser_config" is an empty JSON object.

Response​

Success:

{
    "code": 0 
}

Failure:

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

列出知识库​

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

列出知识库。

请求​

  • 方法：GET
  • URL：/api/v1/datasets?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id}
  • 请求头：
    • '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)
    Specifies the page on which the datasets will be displayed. Defaults to 1.
  • page_size: (Filter parameter)
    The number of datasets on each page. Defaults to 30.
  • orderby: (Filter parameter)
    The field by which datasets should be sorted. Available options:
    • create_time (default)
    • update_time
  • desc: (Filter parameter)
    Indicates whether the retrieved datasets should be sorted in descending order. Defaults to true.
  • name: (Filter parameter)
    The name of the dataset to retrieve.
  • id: (Filter parameter)
    The ID of the dataset to retrieve.

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"
}

获取知识图谱​

GET /api/v1/datasets/{dataset_id}/knowledge_graph

检索指定知识库的知识图谱。

请求​

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/knowledge_graph
  • 请求头：
    • 'Authorization: Bearer <YOUR_API_KEY>'
Request example​
curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
Request parameters​
  • dataset_id: (Path parameter)
    The ID of the target dataset.

Response​

Success:

{
    "code": 0,
    "data": {
        "graph": {
            "directed": false,
            "edges": [
                {
                    "description": "The notice is a document issued to convey risk warnings and operational alerts.<SEP>The notice is a specific instance of a notification document issued under the risk warning framework.",
                    "keywords": ["9", "8"],
                    "source": "notice",
                    "source_id": ["8a46cdfe4b5c11f0a5281a58e595aa1c"],
                    "src_id": "xxx",
                    "target": "xxx",
                    "tgt_id": "xxx",
                    "weight": 17.0
                }
            ],
            "graph": {
                "source_id": ["8a46cdfe4b5c11f0a5281a58e595aa1c", "8a7eb6424b5c11f0a5281a58e595aa1c"]
            },
            "multigraph": false,
            "nodes": [
                {
                    "description": "xxx",
                    "entity_name": "xxx",
                    "entity_type": "ORGANIZATION",
                    "id": "xxx",
                    "pagerank": 0.10804906590624092,
                    "rank": 3,
                    "source_id": ["8a7eb6424b5c11f0a5281a58e595aa1c"]
                }
            ]
        },
        "mind_map": {}
    }
}

Failure:

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

删除知识图谱​

DELETE /api/v1/datasets/{dataset_id}/knowledge_graph

删除指定知识库的知识图谱。

请求​

  • 方法：DELETE
  • URL：/api/v1/datasets/{dataset_id}/knowledge_graph
  • 请求头：
    • 'Authorization: Bearer <YOUR_API_KEY>'
Request example​
curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
Request parameters​
  • dataset_id: (Path parameter)
    The ID of the target dataset.

Response​

Success:

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

Failure:

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

知识库内文件管理​

上传文档​

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

将文档上传到指定知识库。

请求​

  • 方法：POST
  • URL：/api/v1/datasets/{dataset_id}/documents
  • 请求头：
    • 'Content-Type: multipart/form-data'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 表单：
    • '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)
    The ID of the dataset to which the documents will be uploaded.
  • 'file': (Body parameter)
    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!"
}

更新文档​

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

更新指定文档的配置。

请求​

  • 方法：PUT
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "name"：string
    • "meta_fields"：object
    • "chunk_method"：string
    • "parser_config"：object
Request example​
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
     {
          "name": "manual.txt", 
          "chunk_method": "manual", 
          "parser_config": {"chunk_token_num": 128}
     }'

Request parameters​
  • dataset_id: (Path parameter)
    The ID of the associated dataset.
  • document_id: (Path parameter)
    The ID of the document to update.
  • "name": (Body parameter), string
  • "meta_fields": (Body parameter), dict[str, Any] The meta fields of the document.
  • "chunk_method": (Body parameter), string
    The parsing method to apply to the document:
    • "naive": General
    • "manual: Manual
    • "qa": Q&A
    • "table": Table
    • "paper": Paper
    • "book": Book
    • "laws": Laws
    • "presentation": Presentation
    • "picture": Picture
    • "one": One
    • "email": Email
  • "parser_config": (Body parameter), object
    The configuration settings for the dataset parser. The attributes in this JSON object vary with the selected "chunk_method":
    • If "chunk_method" is "naive", the "parser_config" object contains the following attributes:
      • "chunk_token_num": Defaults to 256.
      • "layout_recognize": Defaults to true.
      • "html4excel": Indicates whether to convert Excel documents into HTML format. Defaults to false.
      • "delimiter": Defaults to "\n".
      • "task_page_size": Defaults to 12. For PDF only.
      • "raptor": RAPTOR-specific settings. Defaults to: {"use_raptor": false}.
    • If "chunk_method" is "qa", "manuel", "paper", "book", "laws", or "presentation", the "parser_config" object contains the following attribute:
      • "raptor": RAPTOR-specific settings. Defaults to: {"use_raptor": false}.
    • If "chunk_method" is "table", "picture", "one", or "email", "parser_config" is an empty JSON object.

Response​

Success:

{
    "code": 0
}

Failure:

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

下载文档​

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

从指定知识库下载文档。

请求​

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}
  • 请求头：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 输出：
    • '{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)
    The associated dataset ID.
  • documents_id: (Path parameter)
    The ID of the document to download.

Response​

Success:

This is a test to verify the file download feature.

Failure:

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

列出文档​

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}&create_time_from={timestamp}&create_time_to={timestamp}

列出指定知识库中的文档。

请求​

  • 方法：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}&create_time_from={timestamp}&create_time_to={timestamp}
  • 请求头：
    • '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}&create_time_from={timestamp}&create_time_to={timestamp} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
Request parameters​
  • dataset_id: (Path parameter)
    The associated dataset ID.
  • keywords: (Filter parameter), 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_size: (Filter parameter), integer
    The maximum number of documents on each page. Defaults to 30.
  • orderby: (Filter parameter), string
    The field by which documents should be sorted. Available options:
    • create_time (default)
    • update_time
  • desc: (Filter parameter), boolean
    Indicates whether the retrieved documents should be sorted in descending order. Defaults to true.
  • id: (Filter parameter), string
    The ID of the document to retrieve.
  • create_time_from: (Filter parameter), integer Unix timestamp for filtering documents created after this time. 0 means no filter. Defaults to 0.
  • create_time_to: (Filter parameter), integer Unix timestamp for filtering documents created before this time. 0 means no filter. Defaults to 0.

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_duration": 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 /api/v1/datasets/{dataset_id}/documents

按 ID 删除文档。

请求​

  • 方法：DELETE
  • URL：/api/v1/datasets/{dataset_id}/documents
  • 请求头：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "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)
    The associated dataset ID.
  • "ids": (Body parameter), list[string]
    The IDs of the documents to delete. If it is not specified, all documents in the specified dataset will be deleted.

Response​

Success:

{
    "code": 0
}.

Failure:

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

解析文档​

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

解析指定知识库中的文档。

请求​

  • 方法：POST
  • URL：/api/v1/datasets/{dataset_id}/chunks
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "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)
    The dataset ID.
  • "document_ids": (Body parameter), list[string], Required
    The IDs of the documents to parse.

Response​

Success:

{
    "code": 0
}

Failure:

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

停止解析文档​

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

停止解析指定文档。

请求​

  • 方法：DELETE
  • URL：/api/v1/datasets/{dataset_id}/chunks
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "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)
    The associated dataset ID.
  • "document_ids": (Body parameter), list[string], Required
    The IDs of the documents for which the parsing should be stopped.

Response​

Success:

{
    "code": 0
}

Failure:

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

数据集内块管理​

添加块​

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

向指定数据集中的指定文档添加块。

请求​

  • 方法：POST
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "content"：string
    • "important_keywords"：list[string]
请求示例​
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>"
     }'
请求参数​
  • dataset_id：（路径参数）
    关联的数据集 ID。
  • document_ids：（路径参数）
    关联的文档 ID。
  • "content"：（请求体参数），string，必需
    块的文本内容。
  • "important_keywords（请求体参数），list[string]
    要与块关联的关键词或短语。
  • "questions"（请求体参数），list[string] 如果有给定的问题，嵌入的块将基于它们

响应​

成功：

{
    "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": []
        }
    }
}

失败：

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

列出块​

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

列出指定文档中的块。

请求​

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?keywords={keywords}&page={page}&page_size={page_size}&id={chunk_id}
  • 请求头：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例​
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>'
请求参数​
  • dataset_id：（路径参数）
    关联的数据集 ID。
  • document_id：（路径参数）
    关联的文档 ID。
  • keywords（过滤参数），string
    用于匹配块内容的关键词。
  • page（过滤参数），integer
    指定块将显示在哪一页。默认为 1。
  • page_size（过滤参数），integer
    每页的最大块数。默认为 1024。
  • id（过滤参数），string
    要检索的块 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_duration": 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 /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

按 ID 删除块。

请求​

  • 方法：DELETE
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "chunk_ids"：list[string]
请求示例​
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"]
     }'
请求参数​
  • dataset_id：（路径参数）
    关联的数据集 ID。
  • document_ids：（路径参数）
    关联的文档 ID。
  • "chunk_ids"：（请求体参数），list[string]
    要删除的块 ID。如果未指定，将删除指定文档的所有块。

响应​

成功：

{
    "code": 0
}

失败：

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

更新块​

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

更新指定块的内容或配置。

请求​

  • 方法：PUT
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "content"：string
    • "important_keywords"：list[string]
    • "available"：boolean
请求示例​
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": []  
     }'
请求参数​
  • dataset_id：（路径参数）
    关联的数据集 ID。
  • document_ids：（路径参数）
    关联的文档 ID。
  • chunk_id：（路径参数）
    要更新的块 ID。
  • "content"：（请求体参数），string
    块的文本内容。
  • "important_keywords"：（请求体参数），list[string]
    要与块关联的关键词或短语列表。
  • "available"：（请求体参数）boolean
    块在数据集中的可用性状态。值选项：
    • true：可用（默认）
    • false：不可用

响应​

成功：

{
    "code": 0
}

失败：

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

检索块​

POST /api/v1/retrieval

从指定数据集检索块。

请求​

  • 方法：POST
  • URL：/api/v1/retrieval
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "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
    • "cross_languages"：list[string]
    • "metadata_condition"：object
请求示例​
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"]
     }'
请求参数​
  • "question"：（请求体参数），string，必需
    用户查询或查询关键词。
  • "dataset_ids"：（请求体参数）list[string]
    要搜索的数据集 ID。如果您不设置此参数，请确保设置 "document_ids"。
  • "document_ids"：（请求体参数），list[string]
    要搜索的文档 ID。确保所有选定的文档使用相同的嵌入模型。否则将发生错误。如果您不设置此参数，请确保设置 "dataset_ids"。
  • "page"：（请求体参数），integer
    指定块将显示在哪一页。默认为 1。
  • "page_size"：（请求体参数）
    每页的最大块数。默认为 30。
  • "similarity_threshold"：（请求体参数）
    最小相似性分数。默认为 0.2。
  • "vector_similarity_weight"：（请求体参数），float
    向量余弦相似性的权重。默认为 0.3。如果 x 表示向量余弦相似性的权重，则 (1 - x) 是词项相似性权重。
  • "top_k"：（请求体参数），integer
    参与向量余弦计算的块数。默认为 1024。
  • "rerank_id"：（请求体参数），integer
    重排序模型的 ID。
  • "keyword"：（请求体参数），boolean
    指示是否启用基于关键词的匹配：
    • true：启用基于关键词的匹配。
    • false：禁用基于关键词的匹配（默认）。
  • "highlight"：（请求体参数），boolean
    指定是否在结果中启用匹配词项的高亮显示：
    • true：启用匹配词项的高亮显示。
    • false：禁用匹配词项的高亮显示（默认）。
  • "cross_languages"：（请求体参数）list[string]
    应该翻译成的语言，以实现不同语言的关键词检索。
  • "metadata_condition"：（请求体参数），object
    用于过滤块的元数据条件。

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."
}

聊天助手管理​

创建聊天助手​

POST /api/v1/chats

创建聊天助手。

请求​

  • 方法：POST
  • URL：/api/v1/chats
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "name"：string
    • "avatar"：string
    • "dataset_ids"：list[string]
    • "llm"：object
    • "prompt"：object
请求示例​
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"
}'
请求参数​
  • "name"：（请求体参数），string，必需
    聊天助手的名称。
  • "avatar"：（请求体参数），string
    头像的 Base64 编码。
  • "dataset_ids"：（请求体参数），list[string]
    关联数据集的 ID。
  • "llm"：（请求体参数），object
    要创建的聊天助手的 LLM 设置。如果未明确设置，将生成具有以下值的 JSON 对象作为默认值。llm JSON 对象包含以下属性：
    • "model_name"，string
      聊天模型名称。如果未设置，将使用用户的默认聊天模型。
    • "temperature"：float
      控制模型预测的随机性。较低的温度会产生更保守的响应，而较高的温度会产生更具创意性和多样性的响应。默认为 0.1。
    • "top_p"：float
      也被称为"核采样"，此参数设置一个阈值来选择一个较小的单词集合进行采样。它专注于最可能的单词，切断可能性较低的单词。默认为 0.3
    • "presence_penalty"：float
      通过惩罚对话中已经出现的单词，阻止模型重复相同信息。默认为 0.4。
    • "frequency penalty"：float
      与存在惩罚类似，这减少了模型频繁重复相同单词的倾向。默认为 0.7。
  • "prompt"：（请求体参数），object
    LLM 要遵循的指令。如果未明确设置，将生成具有以下值的 JSON 对象作为默认值。prompt JSON 对象包含以下属性：
    • "similarity_threshold"：float RAGFlow 在检索过程中采用加权关键词相似性和加权向量余弦相似性的组合，或加权关键词相似性和加权重排序分数的组合。此参数设置用户查询和块之间相似性的阈值。如果相似性分数低于此阈值，相应的块将被排除在结果之外。默认值为 0.2。
    • "keywords_similarity_weight"：float 此参数设置关键词相似性在与向量余弦相似性或重排序模型相似性的混合相似性分数中的权重。通过调整此权重，您可以控制关键词相似性相对于其他相似性度量的影响。默认值为 0.7。
    • "top_n"：int 此参数指定相似性分数高于 similarity_threshold 的顶级块数量，这些块将被提供给 LLM。LLM 将仅访问这些"前 N 个"块。默认值为 6。
    • "variables"：object[] 此参数列出了在聊天配置的"系统"字段中使用的变量。请注意：
      • "knowledge" 是一个保留变量，表示检索到的块。
      • "系统"中的所有变量都应该用花括号括起来。
      • 默认值为 [{"key": "knowledge", "optional": true}]。
    • "rerank_model"：string 如果未指定，将使用向量余弦相似性；否则，将使用重排序分数。
    • top_k：int 指基于特定排序标准从列表或集合中重新排序或选择前 k 个项目的过程。默认为 1024。
    • "empty_response"：string 如果在数据集中没有为用户问题检索到任何内容，这将用作响应。要允许 LLM 在找不到任何内容时即兴发挥，请将此项留空。
    • "opener"：string 给用户的开场问候。默认为 "Hi! I am your assistant, can I help you?"。
    • "show_quote"：boolean 指示是否应显示文本来源。默认为 true。
    • "prompt"：string 提示内容。

响应​

成功：

{
    "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
    }
}

失败：

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

更新聊天助手​

PUT /api/v1/chats/{chat_id}

更新指定聊天助手的配置。

请求​

  • 方法：PUT
  • URL：/api/v1/chats/{chat_id}
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "name"：string
    • "avatar"：string
    • "dataset_ids"：list[string]
    • "llm"：object
    • "prompt"：object
请求示例​
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"
     }'

参数​

  • chat_id：（路径参数）
    要更新的聊天助手的 ID。
  • "name"：（请求体参数），string，必需
    聊天助手的修订名称。
  • "avatar"：（请求体参数），string
    头像的 Base64 编码。
  • "dataset_ids"：（请求体参数），list[string]
    关联数据集的 ID。
  • "llm"：（请求体参数），object
    要创建的聊天助手的 LLM 设置。如果未明确设置，将生成具有以下值的字典作为默认值。llm 对象包含以下属性：
    • "model_name"，string
      聊天模型名称。如果未设置，将使用用户的默认聊天模型。
    • "temperature"：float
      控制模型预测的随机性。较低的温度会产生更保守的响应，而较高的温度会产生更具创意性和多样性的响应。默认为 0.1。
    • "top_p"：float
      也被称为"核采样"，此参数设置一个阈值来选择一个较小的单词集合进行采样。它专注于最可能的单词，切断可能性较低的单词。默认为 0.3
    • "presence_penalty"：float
      通过惩罚对话中已经出现的单词，阻止模型重复相同信息。默认为 0.2。
    • "frequency penalty"：float
      与存在惩罚类似，这减少了模型频繁重复相同单词的倾向。默认为 0.7。
  • "prompt"：（请求体参数），object
    LLM 要遵循的指令。prompt 对象包含以下属性：
    • "similarity_threshold"：float RAGFlow 在检索过程中采用加权关键词相似性和加权向量余弦相似性的组合，或加权关键词相似性和加权重排序分数的组合。此参数设置用户查询和块之间相似性的阈值。如果相似性分数低于此阈值，相应的块将被排除在结果之外。默认值为 0.2。
    • "keywords_similarity_weight"：float 此参数设置关键词相似性在与向量余弦相似性或重排序模型相似性的混合相似性分数中的权重。通过调整此权重，您可以控制关键词相似性相对于其他相似性度量的影响。默认值为 0.7。
    • "top_n"：int 此参数指定相似性分数高于 similarity_threshold 的顶级块数量，这些块将被提供给 LLM。LLM 将仅访问这些"前 N 个"块。默认值为 8。
    • "variables"：object[] 此参数列出了在聊天配置的"系统"字段中使用的变量。请注意：
      • "knowledge" 是一个保留变量，表示检索到的块。
      • "系统"中的所有变量都应该用花括号括起来。
      • 默认值为 [{"key": "knowledge", "optional": true}]
    • "rerank_model"：string 如果未指定，将使用向量余弦相似性；否则，将使用重排序分数。
    • "empty_response"：string 如果在数据集中没有为用户问题检索到任何内容，这将用作响应。要允许 LLM 在找不到任何内容时即兴发挥，请将此项留空。
    • "opener"：string 给用户的开场问候。默认为 "Hi! I am your assistant, can I help you?"。
    • "show_quote"：boolean 指示是否应显示文本来源。默认为 true。
    • "prompt"：string 提示内容。

响应​

成功：

{
    "code": 0
}

失败：

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

删除聊天助手​

DELETE /api/v1/chats

按 ID 删除聊天助手。

请求​

  • 方法：DELETE
  • URL：/api/v1/chats
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "ids"：list[string]
请求示例​
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"]
     }'
请求参数​
  • "ids"：（请求体参数），list[string]
    要删除的聊天助手的 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
  • 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
    Specifies the page on which the chat assistants will be displayed. Defaults to 1.
  • page_size: (Filter parameter), integer
    The number of chat assistants on each page. Defaults to 30.
  • orderby: (Filter parameter), string
    The attribute by which the results are sorted. Available options:
    • create_time (default)
    • update_time
  • desc: (Filter parameter), boolean
    Indicates whether the retrieved chat assistants should be sorted in descending order. Defaults to true.
  • id: (Filter parameter), string
    The ID of the chat assistant to retrieve.
  • name: (Filter parameter), 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"
}

会话管理​

与聊天助手创建会话​

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

与聊天助手创建会话。

请求​

  • 方法：POST
  • URL：/api/v1/chats/{chat_id}/sessions
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "name"：string
    • "user_id"：string（可选）
请求示例​
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"
     }'
请求参数​
  • chat_id：（路径参数）
    关联的聊天助手 ID。
  • "name"：（请求体参数），string
    要创建的聊天会话名称。
  • "user_id"：（请求体参数），string
    可选的用户定义 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."
}

更新聊天助手的会话​

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

更新指定聊天助手的会话。

请求​

  • 方法：PUT
  • URL：/api/v1/chats/{chat_id}/sessions/{session_id}
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "name"：string
    • "user_id"：string（可选）
请求示例​
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>"
     }'
请求参数​
  • chat_id：（路径参数）
    关联的聊天助手 ID。
  • session_id：（路径参数）
    要更新的会话 ID。
  • "name"：（请求体参数），string
    会话的修订名称。
  • "user_id"：（请求体参数），string
    可选的用户定义 ID。

Response​

Success:

{
    "code": 0
}

Failure:

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

列出聊天助手的会话​

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

列出与指定聊天助手关联的会话。

请求​

  • 方法：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}
  • 请求头：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例​
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>'
请求参数​
  • chat_id：（路径参数）
    关联的聊天助手 ID。
  • page：（过滤参数），integer
    指定会话将显示在哪一页。默认为 1。
  • page_size：（过滤参数），integer
    每页的会话数。默认为 30。
  • orderby：（过滤参数），string
    会话排序的字段。可用选项：
    • create_time（默认）
    • update_time
  • desc：（过滤参数），boolean
    指示检索到的会话是否应按降序排序。默认为 true。
  • name：（过滤参数）string
    要检索的聊天会话名称。
  • id：（过滤参数），string
    要检索的聊天会话 ID。
  • user_id：（过滤参数），string
    创建会话时传入的可选用户定义 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 /api/v1/chats/{chat_id}/sessions

按 ID 删除聊天助手的会话。

请求​

  • 方法：DELETE
  • URL：/api/v1/chats/{chat_id}/sessions
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "ids"：list[string]
请求示例​
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"]
     }'
请求参数​
  • chat_id：（路径参数）
    关联的聊天助手 ID。
  • "ids"：（请求体参数），list[string]
    要删除的会话 ID。如果未指定，将删除与指定聊天助手关联的所有会话。

Response​

Success:

{
    "code": 0
}

Failure:

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

与聊天助手对话​

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

向指定的聊天助手提问以开始 AI 驱动的对话。

注意

  • 在流式模式下，并非所有响应都包含引用，这取决于系统的判断。

  • 在流式模式下，最后一条消息是空消息：

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

请求​

  • 方法：POST
  • URL：/api/v1/chats/{chat_id}/completions
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "question"：string
    • "stream"：boolean
    • "session_id"：string（可选）
    • "user_id"：string（可选）
请求示例​
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"
     }'
请求参数​
  • chat_id：（路径参数）
    关联的聊天助手 ID。
  • "question"：（请求体参数），string，必需
    开始 AI 驱动对话的问题。
  • "stream"：（请求体参数），boolean
    指示是否以流式方式输出响应：
    • true：启用流式传输（默认）。
    • false：禁用流式传输。
  • "session_id"：（请求体参数）
    会话的 ID。如果未提供，将生成新会话。
  • "user_id"：（请求体参数），string
    可选的用户定义 ID。仅在未提供 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
}

带 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": "",
                    "url": null,
                    "similarity": 0.7,
                    "vector_similarity": 0.0,
                    "term_similarity": 1.0,
                    "doc_type": [],
                    "positions": [
                        ""
                    ]
                }
            ],
            "doc_aggs": [
                {
                    "doc_name": "1.txt",
                    "doc_id": "dd58f58e888511ef89c90242ac120006",
                    "count": 1
                }
            ]
        },
        "prompt": "xxxxxxxxxxx",
        "created_at": 1755055623.6401553,
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data:{
    "code": 0,
    "data": true
}

失败：

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

与代理创建会话​

已弃用

此方法已弃用且不推荐使用。您仍然可以调用它，但请注意调用 与代理对话 将自动为关联的代理生成会话 ID。

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

与代理创建会话。

请求​

  • 方法：POST
  • URL：/api/v1/agents/{agent_id}/sessions?user_id={user_id}
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • 必需参数：str
    • 其他参数： 在 Begin 组件中指定的变量。
请求示例​

如果您的代理中的 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 '{
     }'
请求参数​
  • agent_id：（路径参数）
    关联的代理 ID。
  • user_id：（过滤参数）
    在上传文件时创建会话时用于解析文档（特别是图像）的可选用户定义 ID。

Response​

Success:

{
    "code": 0,
    "data": {
        "agent_id": "dbb4ed366e8611f09690a55a6daec4ef",
        "dsl": {
            "components": {
                "Message:EightyJobsAsk": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Message",
                        "params": {
                            "content": [
                                "{begin@var1}{begin@var2}"
                            ],
                            "debug_inputs": {},
                            "delay_after_error": 2.0,
                            "description": "",
                            "exception_default_value": null,
                            "exception_goto": null,
                            "exception_method": null,
                            "inputs": {},
                            "max_retries": 0,
                            "message_history_window_size": 22,
                            "outputs": {
                                "content": {
                                    "type": "str",
                                    "value": null
                                }
                            },
                            "stream": true
                        }
                    },
                    "upstream": [
                        "begin"
                    ]
                },
                "begin": {
                    "downstream": [
                        "Message:EightyJobsAsk"
                    ],
                    "obj": {
                        "component_name": "Begin",
                        "params": {
                            "debug_inputs": {},
                            "delay_after_error": 2.0,
                            "description": "",
                            "enablePrologue": true,
                            "enable_tips": true,
                            "exception_default_value": null,
                            "exception_goto": null,
                            "exception_method": null,
                            "inputs": {
                                "var1": {
                                    "name": "var1",
                                    "optional": false,
                                    "options": [],
                                    "type": "line",
                                    "value": null
                                },
                                "var2": {
                                    "name": "var2",
                                    "optional": false,
                                    "options": [],
                                    "type": "line",
                                    "value": null
                                }
                            },
                            "max_retries": 0,
                            "message_history_window_size": 22,
                            "mode": "conversational",
                            "outputs": {},
                            "prologue": "Hi! I'm your assistant. What can I do for you?",
                            "tips": "Please fill in the form"
                        }
                    },
                    "upstream": []
                }
            },
            "globals": {
                "sys.conversation_turns": 0,
                "sys.files": [],
                "sys.query": "",
                "sys.user_id": ""
            },
            "graph": {
                "edges": [
                    {
                        "data": {
                            "isHovered": false
                        },
                        "id": "xy-edge__beginstart-Message:EightyJobsAskend",
                        "markerEnd": "logo",
                        "source": "begin",
                        "sourceHandle": "start",
                        "style": {
                            "stroke": "rgba(151, 154, 171, 1)",
                            "strokeWidth": 1
                        },
                        "target": "Message:EightyJobsAsk",
                        "targetHandle": "end",
                        "type": "buttonEdge",
                        "zIndex": 1001
                    }
                ],
                "nodes": [
                    {
                        "data": {
                            "form": {
                                "enablePrologue": true,
                                "inputs": {
                                    "var1": {
                                        "name": "var1",
                                        "optional": false,
                                        "options": [],
                                        "type": "line"
                                    },
                                    "var2": {
                                        "name": "var2",
                                        "optional": false,
                                        "options": [],
                                        "type": "line"
                                    }
                                },
                                "mode": "conversational",
                                "prologue": "Hi! I'm your assistant. What can I do for you?"
                            },
                            "label": "Begin",
                            "name": "begin"
                        },
                        "dragging": false,
                        "id": "begin",
                        "measured": {
                            "height": 112,
                            "width": 200
                        },
                        "position": {
                            "x": 270.64098070942583,
                            "y": -56.320928437811176
                        },
                        "selected": false,
                        "sourcePosition": "left",
                        "targetPosition": "right",
                        "type": "beginNode"
                    },
                    {
                        "data": {
                            "form": {
                                "content": [
                                    "{begin@var1}{begin@var2}"
                                ]
                            },
                            "label": "Message",
                            "name": "Message_0"
                        },
                        "dragging": false,
                        "id": "Message:EightyJobsAsk",
                        "measured": {
                            "height": 57,
                            "width": 200
                        },
                        "position": {
                            "x": 279.5,
                            "y": 190
                        },
                        "selected": true,
                        "sourcePosition": "right",
                        "targetPosition": "left",
                        "type": "messageNode"
                    }
                ]
            },
            "history": [],
            "memory": [],
            "messages": [],
            "path": [],
            "retrieval": [],
            "task_id": "dbb4ed366e8611f09690a55a6daec4ef"
        },
        "id": "0b02fe80780e11f084adcfdc3ed1d902",
        "message": [
            {
                "content": "Hi! I'm your assistant. What can I do for you?",
                "role": "assistant"
            }
        ],
        "source": "agent",
        "user_id": "c3fb861af27a11efa69751e139332ced"
    }
}

Failure:

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

与代理对话​

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

向指定代理提问以开始 AI 驱动的对话。

注意

  • 在流式模式下，并非所有响应都包含引用，这取决于系统的判断。

  • 在流式模式下，最后一条消息是空消息：

    [DONE]

请求​

  • 方法：POST
  • URL：/api/v1/agents/{agent_id}/completions
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "question"：string
    • "stream"：boolean
    • "session_id"：string（可选）
    • "inputs"：object（可选）
    • "user_id"：string（可选）
重要

您可以在请求体中包含自定义参数，但首先确保它们在 Begin 组件中定义。

请求示例​
  • 如果 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 '
     {
        "question": "Hello",
        "stream": false,
     }'
  • 如果 Begin 组件需要参数，请在 "inputs" 的请求体中包含它们的值，如下所示：
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": false,
        "inputs": {
            "line_var": {
                "type": "line",
                "value": "I am line_var"
            },
            "int_var": {
                "type": "integer",
                "value": 1
            },
            "paragraph_var": {
                "type": "paragraph",
                "value": "a\nb\nc"
            },
            "option_var": {
                "type": "options",
                "value": "option 2"
            },
            "boolean_var": {
                "type": "boolean",
                "value": true
            }
        }
    }'

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"
     }'
请求参数​
  • agent_id：（路径参数），string
    关联的代理 ID。
  • "question"：（请求体参数），string，必需
    开始 AI 驱动对话的问题。
  • "stream"：（请求体参数），boolean
    指示是否以流式方式输出响应：
    • true：启用流式传输（默认）。
    • false：禁用流式传输。
  • "session_id"：（请求体参数）
    会话的 ID。如果未提供，将生成新会话。
  • "inputs"：（请求体参数）
    在 Begin 组件中指定的变量。
  • "user_id"：（请求体参数），string
    可选的用户定义 ID。仅在未提供 session_id 时有效。
注意

目前，此方法不支持文件类型输入/变量。作为解决方法，使用以下方式向代理上传文件：
http://{address}/v1/canvas/upload/{agent_id}
您将从其响应体中获得相应的文件 ID。

响应​

未提供 session_id 且在 Begin 组件中未指定变量的成功响应：

流式：

...

data: {
    "event": "message",
    "message_id": "cecdcb0e83dc11f0858253708ecb6573",
    "created_at": 1756364483,
    "task_id": "d1f79142831f11f09cc51795b9eb07c0",
    "data": {
        "content": " themes"
    },
    "session_id": "cd097ca083dc11f0858253708ecb6573"
}

data: {
    "event": "message",
    "message_id": "cecdcb0e83dc11f0858253708ecb6573",
    "created_at": 1756364483,
    "task_id": "d1f79142831f11f09cc51795b9eb07c0",
    "data": {
        "content": "."
    },
    "session_id": "cd097ca083dc11f0858253708ecb6573"
}

data: {
    "event": "message_end",
    "message_id": "cecdcb0e83dc11f0858253708ecb6573",
    "created_at": 1756364483,
    "task_id": "d1f79142831f11f09cc51795b9eb07c0",
    "data": {
        "reference": {
            "chunks": {
                "20": {
                    "id": "4b8935ac0a22deb1",
                    "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.",
                    "document_id": "4bdd2ff65e1511f0907f09f583941b45",
                    "document_name": "INSTALL22.md",
                    "dataset_id": "456ce60c5e1511f0907f09f583941b45",
                    "image_id": "",
                    "positions": [
                        [
                            12,
                            11,
                            11,
                            11,
                            11
                        ]
                    ],
                    "url": null,
                    "similarity": 0.5705525104787287,
                    "vector_similarity": 0.7351750337624289,
                    "term_similarity": 0.5000000005,
                    "doc_type": ""
                }
            },
            "doc_aggs": {
                "INSTALL22.md": {
                    "doc_name": "INSTALL22.md",
                    "doc_id": "4bdd2ff65e1511f0907f09f583941b45",
                    "count": 3
                },
                "INSTALL.md": {
                    "doc_name": "INSTALL.md",
                    "doc_id": "4bd7fdd85e1511f0907f09f583941b45",
                    "count": 2
                },
                "INSTALL(1).md": {
                    "doc_name": "INSTALL(1).md",
                    "doc_id": "4bdfb42e5e1511f0907f09f583941b45",
                    "count": 2
                },
                "INSTALL3.md": {
                    "doc_name": "INSTALL3.md",
                    "doc_id": "4bdab5825e1511f0907f09f583941b45",
                    "count": 1
                }
            }
        }
    },
    "session_id": "cd097ca083dc11f0858253708ecb6573"
}

data:[DONE]

非流式：

{
    "code": 0,
    "data": {
        "created_at": 1756363177,
        "data": {
            "content": "\nTo install Neovim, the process varies depending on your operating system:\n\n### For macOS:\nUsing Homebrew:\n```bash\nbrew install neovim\n```\n\n### For Linux (Debian/Ubuntu):\n```bash\nsudo apt update\nsudo apt install neovim\n```\n\nFor other Linux distributions, you can use their respective package managers or build from source.\n\n### For Windows:\n1. Download the latest Windows installer from the official Neovim GitHub releases page\n2. Run the installer and follow the prompts\n3. Add Neovim to your PATH if not done automatically\n\n### From source (Unix-like systems):\n```bash\ngit clone https://github.com/neovim/neovim.git\ncd neovim\nmake CMAKE_BUILD_TYPE=Release\nsudo make install\n```\n\nAfter installation, you can verify it by running `nvim --version` in your terminal.",
            "created_at": 18129.044975627,
            "elapsed_time": 10.0157331670016,
            "inputs": {
                "var1": {
                    "value": "I am var1"
                },
                "var2": {
                    "value": "I am var2"
                }
            },
            "outputs": {
                "_created_time": 18129.502422278,
                "_elapsed_time": 0.00013378599760471843,
                "content": "\nTo install Neovim, the process varies depending on your operating system:\n\n### For macOS:\nUsing Homebrew:\n```bash\nbrew install neovim\n```\n\n### For Linux (Debian/Ubuntu):\n```bash\nsudo apt update\nsudo apt install neovim\n```\n\nFor other Linux distributions, you can use their respective package managers or build from source.\n\n### For Windows:\n1. Download the latest Windows installer from the official Neovim GitHub releases page\n2. Run the installer and follow the prompts\n3. Add Neovim to your PATH if not done automatically\n\n### From source (Unix-like systems):\n```bash\ngit clone https://github.com/neovim/neovim.git\ncd neovim\nmake CMAKE_BUILD_TYPE=Release\nsudo make install\n```\n\nAfter installation, you can verify it by running `nvim --version` in your terminal."
            },
            "reference": {
                "chunks": {
                    "20": {
                        "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.",
                        "dataset_id": "456ce60c5e1511f0907f09f583941b45",
                        "doc_type": "",
                        "document_id": "4bdd2ff65e1511f0907f09f583941b45",
                        "document_name": "INSTALL22.md",
                        "id": "4b8935ac0a22deb1",
                        "image_id": "",
                        "positions": [
                            [
                                12,
                                11,
                                11,
                                11,
                                11
                            ]
                        ],
                        "similarity": 0.5705525104787287,
                        "term_similarity": 0.5000000005,
                        "url": null,
                        "vector_similarity": 0.7351750337624289
                    }
                },
                "doc_aggs": {
                    "INSTALL(1).md": {
                        "count": 2,
                        "doc_id": "4bdfb42e5e1511f0907f09f583941b45",
                        "doc_name": "INSTALL(1).md"
                    },
                    "INSTALL.md": {
                        "count": 2,
                        "doc_id": "4bd7fdd85e1511f0907f09f583941b45",
                        "doc_name": "INSTALL.md"
                    },
                    "INSTALL22.md": {
                        "count": 3,
                        "doc_id": "4bdd2ff65e1511f0907f09f583941b45",
                        "doc_name": "INSTALL22.md"
                    },
                    "INSTALL3.md": {
                        "count": 1,
                        "doc_id": "4bdab5825e1511f0907f09f583941b45",
                        "doc_name": "INSTALL3.md"
                    }
                }
            }
        },
        "event": "workflow_finished",
        "message_id": "c4692a2683d911f0858253708ecb6573",
        "session_id": "c39f6f9c83d911f0858253708ecb6573",
        "task_id": "d1f79142831f11f09cc51795b9eb07c0"
    }
}

未提供 session_id 且在 Begin 组件中指定了变量的成功响应：

流式：

data:{
    "event": "message",
    "message_id": "0e273472783711f0806e1a6272e682d8",
    "created_at": 1755083830,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": "Hello"
    },
    "session_id": "0e0d1542783711f0806e1a6272e682d8"
}

data:{
    "event": "message",
    "message_id": "0e273472783711f0806e1a6272e682d8",
    "created_at": 1755083830,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": "!"
    },
    "session_id": "0e0d1542783711f0806e1a6272e682d8"
}

data:{
    "event": "message",
    "message_id": "0e273472783711f0806e1a6272e682d8",
    "created_at": 1755083830,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": " How"
    },
    "session_id": "0e0d1542783711f0806e1a6272e682d8"
}

...

data:[DONE]

非流式：

{
    "code": 0,
    "data": {
        "created_at": 1755083779,
        "data": {
            "created_at": 547400.868004651,
            "elapsed_time": 3.5037803899031132,
            "inputs": {
                "boolean_var": {
                    "type": "boolean",
                    "value": true
                },
                "int_var": {
                    "type": "integer",
                    "value": 1
                },
                "line_var": {
                    "type": "line",
                    "value": "I am line_var"
                },
                "option_var": {
                    "type": "options",
                    "value": "option 2"
                },
                "paragraph_var": {
                    "type": "paragraph",
                    "value": "a\nb\nc"
                }
            },
            "outputs": {
                "_created_time": 547400.869271305,
                "_elapsed_time": 0.0001251999055966735,
                "content": "Hello there! How can I assist you today?"
            }
        },
        "event": "workflow_finished",
        "message_id": "effdad8c783611f089261a6272e682d8",
        "session_id": "efe523b6783611f089261a6272e682d8",
        "task_id": "99ee29d6783511f09c921a6272e682d8"
    }
}

在 Begin 组件中指定了变量的成功响应：

流式：

data:{
    "event": "message",
    "message_id": "5b62e790783711f0bc531a6272e682d8",
    "created_at": 1755083960,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": "Hello"
    },
    "session_id": "979e450c781d11f095cb729e3aa55728"
}

data:{
    "event": "message",
    "message_id": "5b62e790783711f0bc531a6272e682d8",
    "created_at": 1755083960,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": "!"
    },
    "session_id": "979e450c781d11f095cb729e3aa55728"
}

data:{
    "event": "message",
    "message_id": "5b62e790783711f0bc531a6272e682d8",
    "created_at": 1755083960,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": " You"
    },
    "session_id": "979e450c781d11f095cb729e3aa55728"
}

...

data:[DONE]

非流式：

{
    "code": 0,
    "data": {
        "created_at": 1755084029,
        "data": {
            "created_at": 547650.750818867,
            "elapsed_time": 1.6227330720284954,
            "inputs": {},
            "outputs": {
                "_created_time": 547650.752800839,
                "_elapsed_time": 9.628792759031057e-05,
                "content": "Hello! It appears you've sent another \"Hello\" without additional context. I'm here and ready to respond to any requests or questions you may have. Is there something specific you'd like to discuss or learn about?"
            }
        },
        "event": "workflow_finished",
        "message_id": "84eec534783711f08db41a6272e682d8",
        "session_id": "979e450c781d11f095cb729e3aa55728",
        "task_id": "99ee29d6783511f09c921a6272e682d8"
    }
}

失败：

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

列出代理会话​

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}

列出与指定代理关联的会话。

请求​

  • 方法：GET
  • URL：/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}
  • 请求头：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例​
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>'
请求参数​
  • agent_id：（路径参数）
    关联的代理 ID。
  • page：（过滤参数），integer
    指定会话将显示在哪一页。默认为 1。
  • page_size：（过滤参数），integer
    每页的会话数。默认为 30。
  • orderby：（过滤参数），string
    会话排序的字段。可用选项：
    • create_time（默认）
    • update_time
  • desc：（过滤参数），boolean
    指示检索到的会话是否应按降序排序。默认为 true。
  • id：（过滤参数），string
    要检索的代理会话 ID。
  • user_id：（过滤参数），string
    创建会话时传入的可选用户定义 ID。
  • dsl：（过滤参数），boolean
    指示是否在响应中包含会话的 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 /api/v1/agents/{agent_id}/sessions

按 ID 删除代理的会话。

请求​

  • 方法：DELETE
  • URL：/api/v1/agents/{agent_id}/sessions
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "ids"：list[string]
请求示例​
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"]
     }'
请求参数​
  • agent_id：（路径参数）
    关联的代理 ID。
  • "ids"：（请求体参数），list[string]
    要删除的会话 ID。如果未指定，将删除与指定代理关联的所有会话。

Response​

Success:

{
    "code": 0
}

Failure:

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

生成相关问题​

POST /api/v1/sessions/related_questions

从用户的原始查询生成五到十个替代问题字符串，以检索更相关的搜索结果。

此操作需要 Bearer Login Token，通常在 24 小时内过期。您可以在浏览器的请求头中轻松找到它，如下所示：

Image

注意

聊天模型根据指令自主确定要生成的问题数量，通常在五到十个之间。

请求​

  • 方法：POST
  • URL：/api/v1/sessions/related_questions
  • 请求头：
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_LOGIN_TOKEN>'
  • 请求体：
    • "question"：string
    • "industry"：string
请求示例​
curl --request POST \
     --url http://{address}/api/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?",
          "industry": "software_development"
     }'
请求参数​
  • "question"：（请求体参数），string 原始用户问题。
  • "industry"：（请求体参数），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'>"
}

代理管理​

列出代理​

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

列出代理。

请求​

  • 方法：GET
  • URL：/api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&title={agent_name}&id={agent_id}
  • 请求头：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例​
curl --request GET \
     --url http://{address}/api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&title={agent_name}&id={agent_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数​
  • page：（过滤参数），integer
    指定代理将显示在哪一页。默认为 1。
  • page_size：（过滤参数），integer
    每页的代理数。默认为 30。
  • orderby：（过滤参数），string
    结果排序的属性。可用选项：
    • create_time（默认）
    • update_time
  • desc：（过滤参数），boolean
    指示检索到的代理是否应按降序排序。默认为 true。
  • id：（过滤参数），string
    要检索的代理 ID。
  • title：（过滤参数），string
    要检索的代理名称。

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."
}

创建代理​

POST /api/v1/agents

创建代理。

请求​

  • 方法：POST
  • URL：/api/v1/agents
  • 请求头：
    • 'Content-Type: application/json
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "title"：string
    • "description"：string
    • "dsl"：object
请求示例​
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 ...
         }
     }'
请求参数​
  • title：（请求体参数），string，必需
    代理的标题。
  • description：（请求体参数），string
    代理的描述。默认为 None。
  • dsl：（请求体参数），object，必需
    代理的画布 DSL 对象。

Response​

Success:

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

Failure:

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

更新代理​

PUT /api/v1/agents/{agent_id}

按 ID 更新代理。

请求​

  • 方法：PUT
  • URL：/api/v1/agents/{agent_id}
  • 请求头：
    • 'Content-Type: application/json
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体：
    • "title"：string
    • "description"：string
    • "dsl"：object
请求示例​
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 ...
         }
     }'
请求参数​
  • agent_id：（路径参数），string
    要更新的代理 ID。
  • title：（请求体参数），string
    代理的标题。
  • description：（请求体参数），string
    代理的描述。
  • dsl：（请求体参数），object
    代理的画布 DSL 对象。

在请求体中仅指定要更改的参数。如果参数不存在或为 None，则不会更新。

Response​

Success:

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

Failure:

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

删除代理​

DELETE /api/v1/agents/{agent_id}

按 ID 删除代理。

请求​

  • 方法：DELETE
  • URL：/api/v1/agents/{agent_id}
  • 请求头：
    • 'Content-Type: application/json
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例​
curl --request DELETE \
     --url http://{address}/api/v1/agents/58af890a2a8911f0a71a11b922ed82d6 \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{}'
请求参数​
  • agent_id：（路径参数），string
    要删除的代理 ID。

响应​

成功：

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

失败：

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