diff --git a/docs.json b/docs.json index d107cc4a..9e99ba9a 100644 --- a/docs.json +++ b/docs.json @@ -713,7 +713,7 @@ "openapi": "zh/api-reference/openapi_chat.json" }, { - "group": "Chatflow", + "group": "对话流", "openapi": "zh/api-reference/openapi_chatflow.json" }, { @@ -2115,6 +2115,14 @@ { "source": "/ja-jp/guides/model-configuration/load-balancing", "destination": "/ja/use-dify/workspace/model-providers#負荷分散の構成" + }, + { + "source": "/api-reference/datasets/get-knowledge-base-list", + "destination": "/api-reference/knowledge-bases/list-knowledge-bases" + }, + { + "source": "/api-reference/数据集/获取知识库列表", + "destination": "/api-reference/知识库/获取知识库列表" } ], "navbar": { diff --git a/en/api-reference/openapi_chat.json b/en/api-reference/openapi_chat.json index 85c9cee2..e8182b82 100644 --- a/en/api-reference/openapi_chat.json +++ b/en/api-reference/openapi_chat.json @@ -8,7 +8,7 @@ "servers": [ { "url": "{api_base_url}", - "description": "The base URL for the Chat App API. Replace {api_base_url} with the actual API base URL provided for your application (e.g., from props.appDetail.api_base_url).", + "description": "The base URL for the Chat App API. Replace {api_base_url} with the actual API base URL provided for your application.", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", @@ -28,7 +28,9 @@ "summary": "Send Chat Message", "description": "Send a request to the chat application.", "operationId": "sendChatMessage", - "tags": ["Chat"], + "tags": [ + "Chats" + ], "requestBody": { "description": "Request body to send a chat message.", "required": true, @@ -39,9 +41,11 @@ }, "examples": { "streaming_example": { - "summary": "Streaming mode example with file", + "summary": "Request Example - Streaming mode", "value": { - "inputs": {}, + "inputs": { + "city": "San Francisco" + }, "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", "conversation_id": "", @@ -54,6 +58,16 @@ } ] } + }, + "blocking_example": { + "summary": "Request Example - Blocking mode", + "value": { + "inputs": {}, + "query": "What are the specs of the iPhone 13 Pro Max?", + "response_mode": "blocking", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "user": "abc-123" + } } } } @@ -61,7 +75,7 @@ }, "responses": { "200": { - "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n- If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkChatEvent` objects.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkChatEvent` objects.", "content": { "application/json": { "schema": { @@ -69,11 +83,11 @@ }, "examples": { "blockingResponse": { - "summary": "Example of a blocking mode response", + "summary": "Response Example - Blocking mode", "value": { "event": "message", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", - "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "mode": "chat", @@ -102,7 +116,7 @@ "document_name": "iPhone List", "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", "score": 0.98457545, - "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" } ] }, @@ -114,252 +128,142 @@ "text/event-stream": { "schema": { "type": "string", - "description": "A stream of Server-Sent Events. Each event is a JSON object prefixed with 'data: ' and suffixed with '\\n\\n'. See `ChunkChatEvent` for possible event structures." + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkChatEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `message_end` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." }, "examples": { "streamingResponseBasic": { - "summary": "Example of a streaming mode response (Basic Assistant)", - "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}\n\n" + "summary": "Response Example - Streaming (Basic)", + "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" }, "streamingResponseAgent": { - "summary": "Example of a streaming mode response (Agent Assistant with agent_thought and message_file)", - "value": "data: {\"event\": \"agent_thought\", \"id\": \"agent_thought_id_1\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"position\": 1, \"thought\": \"Thinking about calling a tool...\", \"tool\": \"dalle3\", \"tool_input\": \"{\\\"dalle3\\\": {\\\"prompt\\\": \\\"a cute cat\\\"}}\", \"created_at\": 1705395332}\n\ndata: {\"event\": \"message_file\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"conversation_id\": \"conv123\"}\n\ndata: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333}\n\ndata: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}\n\n" + "summary": "Response Example - Streaming (Agent)", + "value": "data: {\"event\": \"agent_thought\", \"id\": \"agent_thought_id_1\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"position\": 1, \"thought\": \"Thinking about calling a tool...\", \"tool\": \"dalle3\", \"tool_input\": \"{\\\"dalle3\\\": {\\\"prompt\\\": \\\"a cute cat\\\"}}\", \"created_at\": 1705395332} data: {\"event\": \"message_file\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"conversation_id\": \"conv123\"} data: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333} data: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}" } } } } }, "400": { - "description": "Bad Request. Possible error codes:\n- `invalid_param`: Abnormal parameter input.\n- `app_unavailable`: App configuration unavailable.\n- `provider_not_initialize`: No available model credential configuration.\n- `provider_quota_exceeded`: Model invocation quota insufficient.\n- `model_currently_not_support`: Current model unavailable.\n- `completion_request_error`: Text generation failed.", + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "404": { - "description": "Conversation does not exist.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "500": { - "description": "Internal server error.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - } - } - } - }, - "/files/upload": { - "post": { - "summary": "File Upload", - "description": "Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text. Supports png, jpg, jpeg, webp, gif formats. Uploaded files are for use by the current end-user only.", - "operationId": "uploadChatFile", - "tags": ["Files"], - "requestBody": { - "description": "File upload request. Requires multipart/form-data.", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "The file to be uploaded. Supported image types: png, jpg, jpeg, webp, gif." + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } }, - "user": { - "type": "string", - "description": "User identifier, defined by the developer's rules, must be unique within the application. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "conversation_completed": { + "summary": "conversation_completed", + "value": { + "status": 400, + "code": "conversation_completed", + "message": "The conversation has ended. Please start a new conversation." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } } } } } - } - }, - "responses": { - "200": { - "description": "File uploaded successfully.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponse" - } - } - } - }, - "400": { "$ref": "#/components/responses/BadRequestFile" }, - "413": { "$ref": "#/components/responses/FileTooLarge" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFile" }, - "503": { "$ref": "#/components/responses/S3ErrorFile" }, - "500": { "$ref": "#/components/responses/InternalServerError" } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "Get End User", - "description": "Retrieve an end user by ID.\n\nThis is useful when other APIs return an end-user ID (e.g. `created_by` from File Upload).", - "operationId": "getEndUserChat", - "tags": ["End Users"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "End user ID.", - "schema": { "type": "string", "format": "uuid" } - } - ], - "responses": { - "200": { - "description": "End user retrieved successfully.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetail" } - } - } - }, - "404": { "$ref": "#/components/responses/EndUserNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } - } - } - }, - "/files/{file_id}/preview": { - "get": { - "summary": "File Preview", - "description": "Preview or download uploaded files. This endpoint allows you to access files that have been previously uploaded via the File Upload API. Files can only be accessed if they belong to messages within the requesting application.", - "operationId": "previewChatFile", - "tags": ["Files"], - "parameters": [ - { - "name": "file_id", - "in": "path", - "required": true, - "description": "The unique identifier of the file to preview, obtained from the File Upload API response.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "as_attachment", - "in": "query", - "required": false, - "description": "Whether to force download the file as an attachment. Default is `false` (preview in browser).", - "schema": { - "type": "boolean", - "default": false - } - } - ], - "responses": { - "200": { - "description": "File content returned successfully. Headers set based on file type and request parameters.", - "content": { - "image/png": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - }, - "headers": { - "Content-Type": { - "description": "MIME type of the file", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "File size in bytes (if available)", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "Set to 'attachment' if as_attachment=true", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "Caching headers for performance", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "Set to 'bytes' for audio/video files", - "schema": { - "type": "string", - "example": "bytes" - } - } - } - }, - "400": { - "description": "Bad Request. Possible error codes:\n- `invalid_param`: Abnormal parameter input.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "403": { - "description": "Forbidden. Possible error codes:\n- `file_access_denied`: File access denied or file does not belong to current application.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } }, "404": { - "description": "Not Found. Possible error codes:\n- `file_not_found`: File not found or has been deleted.", + "description": "`not_found` : Conversation does not exist.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } } } }, "500": { - "description": "Internal server error.", + "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -369,15 +273,17 @@ "/chat-messages/{task_id}/stop": { "post": { "summary": "Stop Chat Message Generation", - "description": "Stops a chat message generation task. Only supported in streaming mode.", + "description": "Stops a chat message generation task. Only supported in `streaming` mode.", "operationId": "stopChatMessageGeneration", - "tags": ["Chat"], + "tags": [ + "Chats" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "Task ID, can be obtained from the streaming chunk return of a `/chat-messages` request.", + "description": "Task ID, can be obtained from the streaming chunk return of the [Send Chat Message](/api-reference/chats/send-chat-message) API.", "schema": { "type": "string" } @@ -389,16 +295,19 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { "user": { "type": "string", - "description": "User identifier, must be consistent with the user passed in the send message interface. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "description": "User identifier, must be consistent with the user passed in the send message interface." } } }, "examples": { - "example":{ + "example": { + "summary": "Request Example", "value": { "user": "abc-123" } @@ -407,78 +316,23 @@ } } }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "Message Feedback", - "description": "End-users can provide feedback messages, facilitating application developers to optimize expected outputs.", - "operationId": "postChatMessageFeedback", - "tags": ["Feedback"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "Message ID for which feedback is being provided.", - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/MessageFeedbackRequest" - } - } - } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } - } - } - }, - "/app/feedbacks": { - "get": { - "summary": "Get feedbacks of application", - "description": "Get application's feedbacks.", - "operationId": "getChatAppFeedbacks", - "tags": ["Feedback"], - "parameters": [ - { - "name": "page", - "in": "query", - "description": "(optional) Pagination page number. Default: 1", - "required": false, - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "(optional) Records per page. Default: 20", - "required": false, - "schema": { - "type": "integer", - "default": 20 - } - } - ], "responses": { "200": { - "description": "A list of application feedbacks.", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/AppFeedbacksResponse" + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } } } } @@ -488,10 +342,12 @@ }, "/messages/{message_id}/suggested": { "get": { - "summary": "Next Suggested Questions", + "summary": "Get Next Suggested Questions", "description": "Get next questions suggestions for the current message.", "operationId": "getSuggestedQuestions", - "tags": ["Chat"], + "tags": [ + "Chats" + ], "parameters": [ { "name": "message_id", @@ -506,7 +362,7 @@ "name": "user", "in": "query", "required": true, - "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface.", + "description": "User identifier.", "schema": { "type": "string" } @@ -519,6 +375,78 @@ "application/json": { "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponse" + }, + "examples": { + "suggestedQuestions": { + "summary": "Response Example", + "value": { + "result": "success", + "data": [ + "What colors does the iPhone 13 Pro Max come in?", + "How does the battery compare to iPhone 12?", + "What is the price range?" + ] + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Suggested questions feature is disabled.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Suggested Questions Is Disabled." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Message does not exist.", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } } } } @@ -526,49 +454,435 @@ } } }, - "/messages": { + "/files/upload": { + "post": { + "summary": "Upload File", + "description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", + "operationId": "uploadChatFile", + "tags": [ + "Files" + ], + "requestBody": { + "description": "File upload request. Requires multipart/form-data.", + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "The file to be uploaded. Supported types include images, documents, audio, and video." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer's rules, must be unique within the application." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "File uploaded successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : File size exceeded.", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { "get": { - "summary": "Get Conversation History Messages", - "description": "Returns historical chat records in a scrolling load format, with the first page returning the latest `{limit}` messages, i.e., in reverse order.", - "operationId": "getConversationHistory", - "tags": ["Conversations"], + "summary": "Download File", + "description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", + "operationId": "previewChatFile", + "tags": [ + "Files" + ], "parameters": [ { - "name": "conversation_id", - "in": "query", + "name": "file_id", + "in": "path", "required": true, - "description": "Conversation ID.", - "schema": { "type": "string" } + "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", + "schema": { + "type": "boolean", + "default": false + } }, { "name": "user", "in": "query", - "required": true, - "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface.", - "schema": { "type": "string" } - }, - { - "name": "first_id", - "in": "query", "required": false, - "description": "The ID of the first chat record on the current page, default is null (for fetching the latest). For subsequent pages, use the ID of the first message from the current list to get older messages.", - "schema": { "type": "string" } - }, - { - "name": "limit", - "in": "query", - "required": false, - "description": "How many chat history messages to return in one request, default is 20.", - "schema": { "type": "integer", "default": 20 } + "description": "User identifier, used for end-user context.", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "Successfully retrieved conversation history.", + "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : Access to the requested file is denied.", + "content": { + "application/json": { + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : The requested file was not found.", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "summary": "Get End User Info", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).", + "operationId": "getEndUserChat", + "tags": [ + "End Users" + ], + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "End user ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "End user retrieved successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConversationHistoryResponse" + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "Response Example", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : End user not found.", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/messages/{message_id}/feedbacks": { + "post": { + "summary": "Submit Message Feedback", + "description": "Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.", + "operationId": "postChatMessageFeedback", + "tags": [ + "Feedback" + ], + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "Message ID.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "Request Example", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : Message does not exist.", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/app/feedbacks": { + "get": { + "summary": "List App Feedbacks", + "description": "Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.", + "operationId": "getChatAppFeedbacks", + "tags": [ + "Feedback" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "Page number for pagination.", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of records per page.", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } + } + ], + "responses": { + "200": { + "description": "A list of application feedbacks.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "rating": "like", + "content": "The response accurately answered my question about product specifications.", + "from_source": "user", + "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "from_account_id": null, + "created_at": "2025-01-16T14:30:29Z", + "updated_at": "2025-01-16T14:30:29Z" + }, + { + "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", + "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", + "rating": "dislike", + "content": "The answer was too vague and did not address the specific pricing question.", + "from_source": "user", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", + "from_account_id": null, + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" + } + ] + } + } } } } @@ -578,40 +892,56 @@ }, "/conversations": { "get": { - "summary": "Get Conversations", - "description": "Retrieve the conversation list for the current user, defaulting to the most recent 20 entries.", + "summary": "List Conversations", + "description": "Retrieve the conversation list for the current user, ordered by most recently active.", "operationId": "getConversationsList", - "tags": ["Conversations"], + "tags": [ + "Conversations" + ], "parameters": [ { "name": "user", "in": "query", - "required": true, - "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface.", - "schema": { "type": "string" } + "required": false, + "description": "User identifier.", + "schema": { + "type": "string" + } }, { "name": "last_id", "in": "query", "required": false, - "description": "(Optional) The ID of the last record on the current page (for pagination).", - "schema": { "type": "string" } + "description": "The ID of the last record on the current page (for pagination).", + "schema": { + "type": "string" + } }, { "name": "limit", "in": "query", "required": false, - "description": "(Optional) How many records to return. Default 20, Min 1, Max 100.", - "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } + "description": "Number of records to return.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } }, { "name": "sort_by", "in": "query", "required": false, - "description": "Sorting Field. Default: -updated_at. '-' prefix for descending.", + "description": "Sorting field. Use '-' prefix for descending order.", "schema": { "type": "string", - "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], + "enum": [ + "created_at", + "-created_at", + "updated_at", + "-updated_at" + ], "default": "-updated_at" } } @@ -623,6 +953,555 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsListResponse" + }, + "examples": { + "conversationsList": { + "summary": "Response Example", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Last conversation does not exist (invalid `last_id`).", + "content": { + "application/json": { + "examples": { + "last_conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Last Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/messages": { + "get": { + "summary": "List Conversation Messages", + "description": "Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order.", + "operationId": "getConversationHistory", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier.", + "schema": { + "type": "string" + } + }, + { + "name": "first_id", + "in": "query", + "required": false, + "description": "The ID of the first chat record on the current page. Default is `null` (fetches the latest messages). For subsequent pages, use the ID of the first message from the current list to get older messages.", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of chat history messages to return per request.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved conversation history.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "Response Example", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "parent_message_id": null, + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "status": "normal", + "error": null, + "message_files": [], + "feedback": { + "rating": "like" + }, + "retriever_resources": [], + "agent_thoughts": [], + "created_at": 1705407629, + "extra_contents": [] + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Conversation does not exist.\n- `not_found` : First message does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "first_message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "First Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables": { + "get": { + "summary": "List Conversation Variables", + "description": "Retrieve variables from a specific conversation.", + "operationId": "getConversationVariables", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "The user identifier.", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "The ID of the last record on the current page (for pagination).", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of records to return.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "variable_name", + "in": "query", + "required": false, + "description": "Filter variables by a specific name.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved conversation variables.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariablesResponse" + }, + "examples": { + "conversationVariables": { + "summary": "Response Example", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "dark_mode", + "description": "User preference setting", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Conversation does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/name": { + "post": { + "summary": "Rename Conversation", + "description": "Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations.", + "operationId": "renameConversation", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationRenameRequest" + }, + "examples": { + "renameExample": { + "summary": "Request Example", + "value": { + "name": "iPhone Specs Chat", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Conversation renamed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationListItem" + }, + "examples": { + "renamedConversation": { + "summary": "Response Example", + "value": { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Conversation does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables/{variable_id}": { + "put": { + "summary": "Update Conversation Variable", + "description": "Update the value of a specific conversation variable. The value must match the expected type.", + "operationId": "updateChatConversationVariable", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "variable_id", + "in": "path", + "required": true, + "description": "Variable ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableUpdateRequest" + }, + "examples": { + "updateStringVariable": { + "summary": "Request Example", + "value": { + "value": "new value", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Variable updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableItem" + }, + "examples": { + "updatedVariable": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "new value", + "description": "User preference setting", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Variable value type mismatch.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "type_mismatch": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Value type mismatch: expected string, got integer." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Conversation does not exist.\n- `not_found` : Conversation variable does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "variable_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Variable Not Exists." + } + } } } } @@ -635,139 +1514,93 @@ "summary": "Delete Conversation", "description": "Delete a conversation.", "operationId": "deleteConversation", - "tags": ["Conversations"], + "tags": [ + "Conversations" + ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID.", - "schema": { "type": "string" } + "schema": { + "type": "string" + } } ], "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { "type": "object", - "required": ["user"], "properties": { "user": { "type": "string", - "description": "The user identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "description": "The user identifier." + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "Request Example" + } + } + } + } + }, + "responses": { + "204": { + "description": "Conversation deleted successfully." + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Conversation does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } } } } } } - }, - "responses": { - "204": { "description": "Conversation deleted successfully. No Content." } - } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "Conversation Rename", - "description": "Rename the session. The session name is used for display on clients that support multiple sessions.", - "operationId": "renameConversation", - "tags": ["Conversations"], - "parameters": [ - { - "name": "conversation_id", - "in": "path", - "required": true, - "description": "Conversation ID.", - "schema": { "type": "string" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConversationRenameRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Conversation renamed successfully.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConversationRenameResponse" - } - } - } - } - } - } - }, - "/conversations/{conversation_id}/variables": { - "get": { - "summary": "Get Conversation Variables", - "description": "Retrieve variables from a specific conversation.", - "operationId": "getConversationVariables", - "tags": ["Conversations"], - "parameters": [ - { - "name": "conversation_id", - "in": "path", - "required": true, - "description": "The ID of the conversation to retrieve variables from.", - "schema": { "type": "string" } - }, - { - "name": "user", - "in": "query", - "required": true, - "description": "The user identifier.", - "schema": { "type": "string" } - }, - { - "name": "last_id", - "in": "query", - "required": false, - "description": "(Optional) The ID of the last record on the current page (for pagination).", - "schema": { "type": "string" } - }, - { - "name": "limit", - "in": "query", - "required": false, - "description": "(Optional) How many records to return. Default 20, Min 1, Max 100.", - "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } - }, - { - "name": "variable_name", - "in": "query", - "required": false, - "description": "(Optional) Filter variables by a specific name.", - "schema": { "type": "string" } - } - ], - "responses": { - "200": { - "description": "Successfully retrieved conversation variables.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationVariablesResponse" } - } - } - }, - "404": { "$ref": "#/components/responses/ConversationNotFound" } } } }, "/audio-to-text": { "post": { - "summary": "Speech to Text", - "description": "Convert audio file to text. Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm. File size limit: 15MB.", + "summary": "Convert Audio to Text", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", "operationId": "audioToText", - "tags": ["TTS"], + "tags": [ + "TTS" + ], "requestBody": { "required": true, "content": { @@ -785,6 +1618,130 @@ "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "Response Example", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : Audio file size exceeded the limit.", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : Audio type is not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } } } } @@ -794,38 +1751,107 @@ }, "/text-to-audio": { "post": { - "summary": "Text to Audio", + "summary": "Convert Text to Audio", "description": "Convert text to speech.", "operationId": "textToAudioChat", - "tags": ["TTS"], + "tags": [ + "TTS" + ], "requestBody": { "required": true, "content": { - "multipart/form-data": { + "application/json": { "schema": { - "$ref": "#/components/schemas/TextToAudioFormRequest" + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "Request Example", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } } } } }, "responses": { "200": { - "description": "Audio file generated successfully.", + "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", "content": { - "audio/wav": { + "audio/mpeg": { "schema": { "type": "string", - "format": "binary", - "description": "The generated audio file." + "format": "binary" } } - }, - "headers": { - "Content-Type": { - "description": "The content type of the response, typically `audio/wav` or `audio/mp3`.", - "schema": { - "type": "string", - "example": "audio/wav" + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } } } } @@ -835,10 +1861,12 @@ }, "/info": { "get": { - "summary": "Get Application Basic Information", - "description": "Used to get basic information about this application.", + "summary": "Get App Info", + "description": "Retrieve basic information about this application, including name, description, tags, and mode.", "operationId": "getChatAppInfo", - "tags": ["Application"], + "tags": [ + "Applications" + ], "responses": { "200": { "description": "Basic information of the application.", @@ -846,6 +1874,21 @@ "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "Response Example", + "value": { + "name": "My Chat App", + "description": "A helpful customer service chatbot.", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "chat", + "author_name": "Dify Team" + } + } } } } @@ -855,18 +1898,11 @@ }, "/parameters": { "get": { - "summary": "Get Application Parameters Information", - "description": "Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values.", + "summary": "Get App Parameters", + "description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.", "operationId": "getChatAppParameters", - "tags": ["Application"], - "parameters": [ - { - "name": "user", - "in": "query", - "required": true, - "description": "User identifier, defined by the developer's rules, must be unique within the application.", - "schema": { "type": "string" } - } + "tags": [ + "Applications" ], "responses": { "200": { @@ -875,6 +1911,87 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "Response Example", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : App unavailable or misconfigured.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } } } } @@ -884,10 +2001,12 @@ }, "/meta": { "get": { - "summary": "Get Application Meta Information", - "description": "Used to get icons of tools in this application.", + "summary": "Get App Meta", + "description": "Retrieve metadata about this application, including tool icons and other configuration details.", "operationId": "getChatAppMeta", - "tags": ["Application"], + "tags": [ + "Applications" + ], "responses": { "200": { "description": "Successfully retrieved application meta information.", @@ -895,6 +2014,20 @@ "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "Response Example", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } } } } @@ -904,10 +2037,12 @@ }, "/site": { "get": { - "summary": "Get Application WebApp Settings", - "description": "Used to get the WebApp settings of the application.", + "summary": "Get App WebApp Settings", + "description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.", "operationId": "getChatWebAppSettings", - "tags": ["Application"], + "tags": [ + "Applications" + ], "responses": { "200": { "description": "WebApp settings of the application.", @@ -915,6 +2050,44 @@ "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "Response Example", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "A helpful customer service chatbot.", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Site not found for this application or the workspace has been archived.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } } } } @@ -923,25 +2096,93 @@ } }, "/apps/annotations": { + "post": { + "summary": "Create Annotation", + "description": "Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response.", + "operationId": "createAnnotation", + "tags": [ + "Annotations" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAnnotationRequest" + }, + "examples": { + "createAnnotation": { + "summary": "Request Example", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Annotation created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "createdAnnotation": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 0, + "created_at": 1705407629 + } + } + } + } + } + } + } + }, "get": { - "summary": "Get Annotation List", - "description": "Retrieves a list of annotations for the application.", + "summary": "List Annotations", + "description": "Retrieves a paginated list of annotations for the application. Supports keyword search filtering.", "operationId": "getAnnotationList", - "tags": ["Annotations"], + "tags": [ + "Annotations" + ], "parameters": [ { "name": "page", "in": "query", - "description": "Page number.", + "description": "Page number for pagination.", "required": false, - "schema": { "type": "integer", "default": 1 } + "schema": { + "type": "integer", + "default": 1 + } }, { "name": "limit", "in": "query", - "description": "Number of items returned, default 20, range 1-100.", + "description": "Number of items per page.", "required": false, - "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "keyword", + "in": "query", + "description": "Keyword to filter annotations by question or answer content.", + "required": false, + "schema": { + "type": "string" + } } ], "responses": { @@ -949,31 +2190,29 @@ "description": "Successfully retrieved annotation list.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AnnotationListResponse" } - } - } - } - } - }, - "post": { - "summary": "Create Annotation", - "description": "Creates a new annotation.", - "operationId": "createAnnotation", - "tags": ["Annotations"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" } - } - } - }, - "responses": { - "200": { - "description": "Annotation created successfully.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/AnnotationItem" } + "schema": { + "$ref": "#/components/schemas/AnnotationListResponse" + }, + "examples": { + "annotationList": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 5, + "created_at": 1705407629 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } } } } @@ -983,23 +2222,39 @@ "/apps/annotations/{annotation_id}": { "put": { "summary": "Update Annotation", - "description": "Updates an existing annotation.", + "description": "Updates the question and answer of an existing annotation.", "operationId": "updateAnnotation", - "tags": ["Annotations"], + "tags": [ + "Annotations" + ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, - "description": "Annotation ID.", - "schema": { "type": "string" } + "description": "The unique identifier of the annotation to update.", + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" } + "schema": { + "$ref": "#/components/schemas/UpdateAnnotationRequest" + }, + "examples": { + "updateAnnotation": { + "summary": "Request Example", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." + } + } + } } } }, @@ -1008,7 +2263,55 @@ "description": "Annotation updated successfully.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AnnotationItem" } + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "updatedAnnotation": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", + "hit_count": 5, + "created_at": 1705407629 + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Insufficient permissions to edit annotations.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Annotation does not exist.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } } } } @@ -1016,43 +2319,104 @@ }, "delete": { "summary": "Delete Annotation", - "description": "Deletes an annotation.", + "description": "Deletes an annotation and its associated hit history.", "operationId": "deleteAnnotation", - "tags": ["Annotations"], + "tags": [ + "Annotations" + ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, - "description": "Annotation ID.", - "schema": { "type": "string" } + "description": "The unique identifier of the annotation to delete.", + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { - "204": { "description": "Annotation deleted successfully. No Content." } + "204": { + "description": "Annotation deleted successfully." + }, + "403": { + "description": "`forbidden` : Insufficient permissions to edit annotations.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Annotation does not exist.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } } } }, "/apps/annotation-reply/{action}": { "post": { - "summary": "Initial Annotation Reply Settings", - "description": "Enable or disable annotation reply settings and configure embedding models. This interface is executed asynchronously.", + "summary": "Configure Annotation Reply", + "description": "Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.", "operationId": "initialAnnotationReplySettings", - "tags": ["Annotations"], + "tags": [ + "Annotations" + ], "parameters": [ { "name": "action", "in": "path", "required": true, - "description": "Action, can only be 'enable' or 'disable'.", - "schema": { "type": "string", "enum": ["enable", "disable"] } + "description": "Action to perform.", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" } + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" + }, + "examples": { + "enableAnnotationReply": { + "summary": "Request Example", + "value": { + "score_threshold": 0.9, + "embedding_provider_name": "openai", + "embedding_model_name": "text-embedding-3-small" + } + } + } } } }, @@ -1061,7 +2425,18 @@ "description": "Annotation reply settings task initiated.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" } + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" + }, + "examples": { + "annotationReplyResponse": { + "summary": "Response Example", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "waiting" + } + } + } } } } @@ -1070,24 +2445,35 @@ }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { - "summary": "Query Initial Annotation Reply Settings Task Status", - "description": "Queries the status of an asynchronously executed annotation reply settings task.", + "summary": "Get Annotation Reply Job Status", + "description": "Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", "operationId": "getInitialAnnotationReplySettingsStatus", - "tags": ["Annotations"], + "tags": [ + "Annotations" + ], "parameters": [ { "name": "action", "in": "path", "required": true, - "description": "Action, must be the same as in the initial settings call ('enable' or 'disable').", - "schema": { "type": "string", "enum": ["enable", "disable"] } + "description": "Action type, must match the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call.", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } }, { "name": "job_id", "in": "path", "required": true, - "description": "Job ID obtained from the initial settings call.", - "schema": { "type": "string" } + "description": "Job ID returned by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -1095,7 +2481,36 @@ "description": "Successfully retrieved task status.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" } + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "Response Example", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : The specified job does not exist.", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "The job does not exist." + } + } + } } } } @@ -1109,137 +2524,123 @@ "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", - "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with 'Bearer '. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" } }, "responses": { - "BadRequestFile": { - "description": "Bad Request for file operations. Possible error codes:\n- `no_file_uploaded`: A file must be provided.\n- `too_many_files`: Currently only one file is accepted.\n- `unsupported_preview`: The file does not support preview.\n- `unsupported_estimate`: The file does not support estimation.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "FileTooLarge": { - "description": "`file_too_large`: The file is too large.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "UnsupportedFileTypeFile": { - "description": "`unsupported_file_type`: Unsupported extension. (Note: The description for `/files/upload` lists image types, while this generic error mentions document files. This might indicate a context-specific message from the backend).", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "S3ErrorFile": { - "description": "Service Unavailable for S3 operations. Possible error codes:\n- `s3_connection_failed`: Unable to connect to S3 service.\n- `s3_permission_denied`: No permission to upload files to S3.\n- `s3_file_too_large`: File exceeds S3 size limit.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "InternalServerError": { - "description": "Internal server error.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "SuccessResult": { - "description": "Operation successful.", - "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } - }, - "ConversationNotFound": { - "description": "Conversation not found. Error code: `conversation_not_exists`", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "EndUserNotFound": { - "description": "End user not found. Error code: `end_user_not_found`", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } + "SuccessResult": { + "description": "Operation successful.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Result status." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } } + } }, "schemas": { "ChatRequest": { "type": "object", - "required": ["query", "user"], + "required": [ + "inputs", + "query", + "user" + ], "properties": { "query": { "type": "string", - "description": "User Input/Question content." + "description": "User input/question content." }, "inputs": { "type": "object", - "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs. Default {}.", - "additionalProperties": true, - "default": {} + "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", + "additionalProperties": true }, "response_mode": { "type": "string", - "enum": ["streaming", "blocking"], - "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes; not supported in Agent Assistant mode). Cloudflare timeout is 100s.", - "default": "streaming" + "enum": [ + "streaming", + "blocking" + ], + "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes; not supported in Agent Assistant mode). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior." }, "user": { "type": "string", - "description": "User identifier, unique within the application. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "description": "User identifier, unique within the application. This identifier scopes data access — conversations, messages, and files are only visible when queried with the same `user` value." }, "conversation_id": { "type": "string", - "description": "Conversation ID to continue a conversation. Pass the previous message's conversation_id." + "description": "Conversation ID to continue a conversation. Pass the previous message's `conversation_id`. To start a new conversation, omit this field or pass an empty string. The response will return a `conversation_id` — pass it in subsequent messages to continue that conversation." }, "files": { "type": "array", + "description": "File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`.", "items": { - "$ref": "#/components/schemas/InputFileObject" - }, - "description": "File list (images) for Vision-capable models." + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "File type." + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file." + }, + "url": { + "type": "string", + "format": "url", + "description": "File URL (required when `transfer_method` is `remote_url`)." + }, + "upload_file_id": { + "type": "string", + "description": "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`)." + } + } + } }, "auto_generate_name": { "type": "boolean", - "description": "Auto-generate conversation title. Default `true`. If `false`, use conversation rename API with `auto_generate: true` for async title generation.", + "description": "Auto-generate conversation title. If `false`, use the [Rename Conversation](/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation.", "default": true } } }, - "InputFileObject": { - "type": "object", - "required": ["type", "transfer_method"], - "properties": { - "type": { - "type": "string", - "enum": ["image"], - "description": "Supported type: `image`." - }, - "transfer_method": { - "type": "string", - "enum": ["remote_url", "local_file"], - "description": "Transfer method, `remote_url` for image URL / `local_file` for file upload" - }, - "url": { - "type": "string", - "format": "url", - "description": "Image URL (when the transfer method is `remote_url`)" - }, - "upload_file_id": { - "type": "string", - "description": "Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`)" - } - }, - "anyOf": [ - { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } - }, - { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } - } - ] - }, "ChatCompletionResponse": { "type": "object", - "description": "Response object for blocking mode chat completion.", "properties": { "event": { "type": "string", - "description": "Event type, fixed as `message`.", - "example": "message" + "description": "Event type, fixed as `message`." }, "task_id": { "type": "string", @@ -1249,12 +2650,12 @@ "id": { "type": "string", "format": "uuid", - "description": "Unique ID of this response/message event." + "description": "Unique ID of this response event." }, "message_id": { "type": "string", "format": "uuid", - "description": "Unique message ID." + "description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints." }, "conversation_id": { "type": "string", @@ -1263,8 +2664,7 @@ }, "mode": { "type": "string", - "description": "App mode, fixed as `chat`.", - "example": "chat" + "description": "App mode, fixed as `chat`." }, "answer": { "type": "string", @@ -1272,11 +2672,17 @@ }, "metadata": { "type": "object", + "description": "Metadata including usage and retriever resources.", "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, + "usage": { + "$ref": "#/components/schemas/Usage" + }, "retriever_resources": { "type": "array", - "items": { "$ref": "#/components/schemas/RetrieverResource" } + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } } } }, @@ -1290,12 +2696,22 @@ "ChunkChatEvent": { "type": "object", "description": "Base schema for Server-Sent Event chunks in streaming mode.", - "required": ["event"], "properties": { "event": { "type": "string", "description": "The type of event.", - "enum": ["message", "agent_message", "tts_message", "tts_message_end", "agent_thought", "message_file", "message_end", "message_replace", "error", "ping"] + "enum": [ + "message", + "agent_message", + "tts_message", + "tts_message_end", + "agent_thought", + "message_file", + "message_end", + "message_replace", + "error", + "ping" + ] } }, "discriminator": { @@ -1316,86 +2732,153 @@ }, "StreamEventBase": { "type": "object", + "description": "Base properties for stream events.", "properties": { - "task_id": { "type": "string", "format": "uuid", "description": "Task ID." }, - "message_id": { "type": "string", "format": "uuid", "description": "Unique message ID." }, - "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, - "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." } + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + } } }, "StreamEventChatMessage": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "required": ["answer"], "properties": { - "answer": { "type": "string", "description": "LLM returned text chunk." } + "answer": { + "type": "string", + "description": "LLM returned text chunk." + } } } ] }, "StreamEventChatAgentMessage": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "required": ["answer"], "properties": { - "answer": { "type": "string", "description": "LLM returned text chunk (Agent mode)." } + "answer": { + "type": "string", + "description": "LLM returned text chunk (Agent mode)." + } } } ] }, "StreamEventChatTtsMessage": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "TTS audio stream event (base64 encoded Mp3). Available if auto-play enabled.", - "required": ["audio"], "properties": { - "audio": { "type": "string", "format": "byte", "description": "Base64 encoded audio chunk." } + "audio": { + "type": "string", + "format": "byte", + "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." + } } } ] }, "StreamEventChatTtsMessageEnd": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "TTS audio stream end event.", - "required": ["audio"], "properties": { - "audio": { "type": "string", "description": "Empty string for end event." } + "audio": { + "type": "string", + "description": "Empty string. Signals the end of the audio stream." + } } } ] }, "StreamEventChatAgentThought": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Agent thought, LLM thinking, tool call details (Agent mode).", - "required": ["id", "position"], "properties": { - "id": { "type": "string", "format": "uuid", "description": "Agent thought ID." }, - "position": { "type": "integer", "description": "Position of this thought in the sequence for the message." }, - "thought": { "type": "string", "description": "What LLM is thinking." }, - "observation": { "type": "string", "description": "Response from tool calls." }, - "tool": { "type": "string", "description": "List of tools called, split by ';'." }, - "tool_input": { "type": "string", "description": "Input of tools in JSON format. Example: {\"dalle3\": {\"prompt\": \"a cute cat\"}}." }, + "id": { + "type": "string", + "format": "uuid", + "description": "Agent thought ID." + }, + "position": { + "type": "integer", + "description": "Position of this thought in the sequence for the message." + }, + "thought": { + "type": "string", + "description": "What LLM is thinking." + }, + "observation": { + "type": "string", + "description": "Response from tool calls." + }, + "tool": { + "type": "string", + "description": "List of tools called, split by `;`." + }, + "tool_input": { + "type": "string", + "description": "Input of tools in JSON format." + }, "message_files": { "type": "array", - "items": { "type": "string", "format": "uuid" }, - "description": "File IDs of files related to this thought (e.g., generated by a tool)." + "items": { + "type": "string", + "format": "uuid" + }, + "description": "File IDs of files related to this thought." } } } @@ -1403,37 +2886,70 @@ }, "StreamEventChatMessageFile": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, { "type": "object", "description": "Message file event, a new file created by a tool.", - "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { - "id": { "type": "string", "format": "uuid", "description": "File unique ID." }, - "type": { "type": "string", "enum": ["image"], "description": "File type, currently only 'image'." }, - "belongs_to": { "type": "string", "enum": ["assistant"], "description": "Who this file belongs to, always 'assistant' here." }, - "url": { "type": "string", "format": "url", "description": "Remote URL of the file." }, - "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID." } + "id": { + "type": "string", + "format": "uuid", + "description": "File unique ID." + }, + "type": { + "type": "string", + "description": "File type, e.g. `image`." + }, + "belongs_to": { + "type": "string", + "description": "Who this file belongs to. Always `assistant` for tool-generated files." + }, + "url": { + "type": "string", + "format": "url", + "description": "Remote URL of the file." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + } } } ] }, "StreamEventChatMessageEnd": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Message end event, streaming has ended.", - "required": ["metadata"], "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, "metadata": { "type": "object", + "description": "Metadata including usage and retriever resources.", "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, + "usage": { + "$ref": "#/components/schemas/Usage" + }, "retriever_resources": { "type": "array", - "items": { "$ref": "#/components/schemas/RetrieverResource" } + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } } } } @@ -1443,37 +2959,61 @@ }, "StreamEventChatMessageReplace": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Message content replacement event (e.g., due to content moderation).", - "required": ["answer"], "properties": { - "answer": { "type": "string", "description": "Replacement content." } + "answer": { + "type": "string", + "description": "Replacement content." + }, + "reason": { + "type": "string", + "description": "Reason for the content replacement." + } } } ] }, "StreamEventChatError": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Error event during streaming.", - "required": ["status", "code", "message"], "properties": { - "status": { "type": "integer", "description": "HTTP status code." }, - "code": { "type": "string", "description": "Error code." }, - "message": { "type": "string", "description": "Error message." } + "status": { + "type": "integer", + "description": "HTTP status code." + }, + "code": { + "type": "string", + "description": "Error code." + }, + "message": { + "type": "string", + "description": "Error message." + } } } ] }, "StreamEventChatPing": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, { "type": "object", "description": "Ping event to keep connection alive." @@ -1484,72 +3024,301 @@ "type": "object", "description": "Model usage information.", "properties": { - "prompt_tokens": { "type": "integer" }, - "prompt_unit_price": { "type": "string", "format": "decimal" }, - "prompt_price_unit": { "type": "string", "format": "decimal" }, - "prompt_price": { "type": "string", "format": "decimal" }, - "completion_tokens": { "type": "integer" }, - "completion_unit_price": { "type": "string", "format": "decimal" }, - "completion_price_unit": { "type": "string", "format": "decimal" }, - "completion_price": { "type": "string", "format": "decimal" }, - "total_tokens": { "type": "integer" }, - "total_price": { "type": "string", "format": "decimal" }, - "currency": { "type": "string", "example": "USD" }, - "latency": { "type": "number", "format": "double" } + "prompt_tokens": { + "type": "integer", + "description": "Number of tokens in the prompt." + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per prompt token." + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for prompt tokens." + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "Total price for prompt tokens." + }, + "completion_tokens": { + "type": "integer", + "description": "Number of tokens in the completion." + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per completion token." + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for completion tokens." + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "Total price for completion tokens." + }, + "total_tokens": { + "type": "integer", + "description": "Total number of tokens used." + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "Total price for all tokens." + }, + "currency": { + "type": "string", + "description": "Currency for pricing." + }, + "latency": { + "type": "number", + "format": "double", + "description": "Latency in seconds." + } } }, "RetrieverResource": { "type": "object", - "description": "Citation and Attribution information for a resource.", + "description": "Citation and attribution information for a retriever resource.", "properties": { - "position": { "type": "integer", "description": "Position of the resource in the list." }, - "dataset_id": { "type": "string", "format": "uuid", "description": "ID of the dataset." }, - "dataset_name": { "type": "string", "description": "Name of the dataset." }, - "document_id": { "type": "string", "format": "uuid", "description": "ID of the document." }, - "document_name": { "type": "string", "description": "Name of the document." }, - "segment_id": { "type": "string", "format": "uuid", "description": "ID of the specific segment within the document." }, - "score": { "type": "number", "format": "float", "description": "Relevance score of the resource." }, - "content": { "type": "string", "description": "Content snippet from the resource." } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of the retriever resource." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "ID of the message this resource belongs to." + }, + "position": { + "type": "integer", + "description": "Position of the resource in the list." + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "ID of the knowledge base." + }, + "dataset_name": { + "type": "string", + "description": "Name of the knowledge base." + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "ID of the document." + }, + "document_name": { + "type": "string", + "description": "Name of the document." + }, + "data_source_type": { + "type": "string", + "description": "Type of the data source." + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "ID of the specific chunk within the document." + }, + "score": { + "type": "number", + "format": "float", + "description": "Relevance score of the resource." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this chunk was hit." + }, + "word_count": { + "type": "integer", + "description": "Word count of the chunk." + }, + "segment_position": { + "type": "integer", + "description": "Position of the chunk within the document." + }, + "index_node_hash": { + "type": "string", + "description": "Hash of the index node." + }, + "content": { + "type": "string", + "description": "Content snippet from the resource." + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary of the chunk content." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." + } } }, "FileUploadResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" }, - "size": { "type": "integer" }, - "extension": { "type": "string" }, - "mime_type": { "type": "string" }, - "created_by": { "type": "string", "format": "uuid" }, - "created_at": { "type": "integer", "format": "int64" } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique file ID." + }, + "name": { + "type": "string", + "description": "File name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "nullable": true, + "description": "File extension." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Upload timestamp (Unix epoch seconds)." + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "Preview URL for the file." + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "Source URL of the file." + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "Original URL of the file." + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated user." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated tenant." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated conversation." + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "Storage key for the file." + } } }, "EndUserDetail": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "Tenant ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Application ID." + }, + "type": { + "type": "string", + "description": "End user type. Always `service_api` for Service API users." + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/api-reference/chats/send-chat-message))." + }, + "name": { + "type": "string", + "nullable": true, + "description": "End user name." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request." + }, + "session_id": { + "type": "string", + "description": "Session identifier. Defaults to the `external_user_id` value." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } } }, "MessageFeedbackRequest": { "type": "object", - "required": ["user"], + "description": "Request body for submitting message feedback.", + "required": [ + "user" + ], "properties": { "rating": { "type": "string", - "enum": ["like", "dislike", null], - "nullable": true + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "Feedback rating. Set to `null` to revoke previously submitted feedback." }, - "user": { "type": "string" }, - "content": { "type": "string" } + "user": { + "type": "string", + "description": "User identifier, defined by the developer, must ensure uniqueness within the application." + }, + "content": { + "type": "string", + "description": "Optional text feedback providing additional detail." + } } }, "AppFeedbacksResponse": { @@ -1557,171 +3326,467 @@ "properties": { "data": { "type": "array", - "items": { "$ref": "#/components/schemas/FeedbackItem" } + "description": "List of feedback items.", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } } } }, "FeedbackItem": { "type": "object", + "description": "A single feedback item.", "properties": { - "id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "message_id": { "type": "string", "format": "uuid" }, - "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, - "content": { "type": "string" }, - "from_source": { "type": "string" }, - "from_end_user_id": { "type": "string", "format": "uuid" }, - "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "Feedback ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "Application ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + }, + "content": { + "type": "string", + "nullable": true, + "description": "Optional text feedback." + }, + "from_source": { + "type": "string", + "description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console." + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "End user ID who submitted the feedback. Present when `from_source` is `user`." + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Account ID who submitted the feedback. Present when `from_source` is `admin`." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } } }, "SuggestedQuestionsResponse": { "type": "object", "properties": { - "result": { "type": "string", "example": "success" }, + "result": { + "type": "string", + "description": "Result status." + }, "data": { "type": "array", - "items": { "type": "string" }, - "example": ["a", "b", "c"] + "items": { + "type": "string" + }, + "description": "List of suggested questions." } } }, "ConversationHistoryResponse": { "type": "object", "properties": { - "limit": { "type": "integer" }, - "has_more": { "type": "boolean" }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more messages." + }, "data": { "type": "array", - "items": { "$ref": "#/components/schemas/ConversationMessageItem" } + "description": "List of messages.", + "items": { + "$ref": "#/components/schemas/ConversationMessageItem" + } } } }, "ConversationMessageItem": { "type": "object", + "description": "A single message in a conversation.", "properties": { - "id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "inputs": { "type": "object", "additionalProperties": true }, - "query": { "type": "string" }, - "answer": { "type": "string" }, + "id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "parent_message_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Parent message ID for threaded conversations." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for this message." + }, + "query": { + "type": "string", + "description": "User query text." + }, + "answer": { + "type": "string", + "description": "Assistant answer text." + }, + "status": { + "type": "string", + "description": "Message status. `normal` for successful messages, `error` when generation failed." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if `status` is `error`." + }, "message_files": { "type": "array", - "items": { "$ref": "#/components/schemas/MessageFileItem" } + "description": "Files attached to this message.", + "items": { + "$ref": "#/components/schemas/MessageFileItem" + } }, "feedback": { "type": "object", "nullable": true, + "description": "User feedback for this message.", "properties": { - "rating": { "type": "string", "enum": ["like", "dislike"] } + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + } } }, "retriever_resources": { "type": "array", - "items": { "$ref": "#/components/schemas/RetrieverResource" } + "description": "Retriever resources used for this message.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } }, "agent_thoughts": { "type": "array", - "items": { "$ref": "#/components/schemas/AgentThoughtItem" } + "description": "Agent thoughts for this message.", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } }, - "created_at": { "type": "integer", "format": "int64" } + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." + }, + "extra_contents": { + "type": "array", + "description": "Additional execution content associated with this message, such as human input form data.", + "items": { + "type": "object", + "additionalProperties": true + } + } } }, "MessageFileItem": { "type": "object", + "description": "A file attached to a message.", "properties": { - "id": { "type": "string", "format": "uuid" }, - "type": { "type": "string", "description": "File type, e.g., 'image'." }, - "url": { "type": "string", "format": "url", "description": "Preview image URL." }, - "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "Who this file belongs to." } + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "Original filename." + }, + "type": { + "type": "string", + "description": "File type, e.g., `image`." + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "Preview URL for the file." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "size": { + "type": "integer", + "nullable": true, + "description": "File size in bytes." + }, + "transfer_method": { + "type": "string", + "description": "Transfer method used. `remote_url` for URL-based files, `local_file` for uploaded files, `tool_file` for tool-generated files." + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "Who this file belongs to. `user` for user-uploaded files, `assistant` for assistant-generated files." + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Upload file ID if transferred via `local_file`." + } } }, "AgentThoughtItem": { "type": "object", + "description": "An agent thought step in the message.", "properties": { - "id": { "type": "string", "format": "uuid", "description": "Agent thought ID." }, - "message_id": { "type": "string", "format": "uuid", "description": "Unique message ID this thought belongs to." }, - "position": { "type": "integer", "description": "Position of this thought." }, - "thought": { "type": "string", "description": "What LLM is thinking." }, - "tool": { "type": "string", "description": "Tools called, split by ';'." }, - "tool_input": { "type": "string", "description": "Input of tools in JSON format." }, - "observation": { "type": "string", "description": "Response from tool calls." }, - "files": { - "type": "array", - "items": { "type": "string", "format": "uuid" }, - "description": "File IDs related to this thought (from example, Markdown text says 'message_files')." + "id": { + "type": "string", + "format": "uuid", + "description": "Agent thought ID." }, - "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." } + "chain_id": { + "type": "string", + "nullable": true, + "description": "Chain ID for this thought." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID this thought belongs to." + }, + "position": { + "type": "integer", + "description": "Position of this thought." + }, + "thought": { + "type": "string", + "description": "What LLM is thinking." + }, + "tool": { + "type": "string", + "description": "Tools called, split by `;`." + }, + "tool_labels": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Labels for tools used." + }, + "tool_input": { + "type": "string", + "description": "Input of tools in JSON format." + }, + "observation": { + "type": "string", + "description": "Response from tool calls." + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "File IDs related to this thought." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + } } }, "ConversationsListResponse": { "type": "object", "properties": { - "limit": { "type": "integer" }, - "has_more": { "type": "boolean" }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more conversations." + }, "data": { "type": "array", - "items": { "$ref": "#/components/schemas/ConversationListItem" } + "description": "List of conversations.", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } } } }, "ConversationListItem": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" }, - "inputs": { "type": "object", "additionalProperties": true }, - "status": { "type": "string" }, - "introduction": { "type": "string" }, - "created_at": { "type": "integer", "format": "int64" }, - "updated_at": { "type": "integer", "format": "int64" } + "id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "name": { + "type": "string", + "description": "Conversation name." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the conversation." + }, + "status": { + "type": "string", + "description": "Conversation status. `normal` for active conversations." + }, + "introduction": { + "type": "string", + "description": "Conversation introduction." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update timestamp." + } } }, "ConversationRenameRequest": { "type": "object", - "required": ["user"], + "description": "Request body for renaming a conversation.", "properties": { - "name": { "type": "string", "description": "(Optional) The name of the conversation. Omit if auto_generate is true." }, - "auto_generate": { "type": "boolean", "default": false, "description": "(Optional) Automatically generate the title. Default false." }, - "user": { "type": "string", "description": "The user identifier." } + "name": { + "type": "string", + "description": "The name of the conversation. Required when `auto_generate` is `false`." + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "Automatically generate the conversation name. When `true`, the `name` field is ignored." + }, + "user": { + "type": "string", + "description": "The user identifier." + } } }, - "ConversationRenameResponse": { - "$ref": "#/components/schemas/ConversationListItem" - }, "ConversationVariablesResponse": { - "type": "object", - "properties": { - "limit": { "type": "integer", "description": "Number of items per page." }, - "has_more": { "type": "boolean", "description": "Whether there is a next page." }, - "data": { - "type": "array", - "items": { "$ref": "#/components/schemas/ConversationVariableItem" } - } + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there is a next page." + }, + "data": { + "type": "array", + "description": "List of conversation variables.", + "items": { + "$ref": "#/components/schemas/ConversationVariableItem" + } } + } }, "ConversationVariableItem": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "Variable ID." }, - "name": { "type": "string", "description": "Variable name." }, - "value_type": { "type": "string", "description": "Variable type (string, number, object, json, etc.)." }, - "value": { "type": "string", "description": "Variable value (can be a JSON string for complex types)." }, - "description": { "type": "string", "description": "Variable description." }, - "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." }, - "updated_at": { "type": "integer", "format": "int64", "description": "Last update timestamp." } + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Variable ID." + }, + "name": { + "type": "string", + "description": "Variable name." + }, + "value_type": { + "type": "string", + "description": "Variable value type. Possible values: `string`, `number`, `object`, `secret`, `file`, `boolean`, `array[any]`, `array[string]`, `array[number]`, `array[object]`, `array[file]`, `array[boolean]`." + }, + "value": { + "type": "string", + "description": "Variable value (can be a JSON string for complex types)." + }, + "description": { + "type": "string", + "description": "Variable description." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update timestamp." } + } + }, + "ConversationVariableUpdateRequest": { + "type": "object", + "description": "Request body for updating a conversation variable.", + "required": [ + "value" + ], + "properties": { + "value": { + "description": "The new value for the variable. Must match the variable's expected type." + }, + "user": { + "type": "string", + "description": "User identifier." + } + } }, "AudioToTextRequest": { "type": "object", - "required": ["file", "user"], + "description": "Request body for audio-to-text conversion.", + "required": [ + "file" + ], "properties": { "file": { "type": "string", "format": "binary", - "description": "Audio file. Supported: mp3, mp4, mpeg, mpga, m4a, wav, webm. Limit: 15MB." + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `30 MB`." }, "user": { "type": "string", @@ -1732,92 +3797,225 @@ "AudioToTextResponse": { "type": "object", "properties": { - "text": { "type": "string", "description": "Output text from speech recognition." } + "text": { + "type": "string", + "description": "Output text from speech recognition." + } } }, - "TextToAudioFormRequest": { + "TextToAudioRequest": { "type": "object", - "required": ["user"], + "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", "properties": { "message_id": { "type": "string", "format": "uuid", - "description": "Message ID (priority if both text and message_id provided)." + "description": "Message ID. Takes priority over `text` when both are provided." }, "text": { "type": "string", - "description": "Speech content." + "description": "Speech content to convert." }, "user": { "type": "string", "description": "User identifier." + }, + "voice": { + "type": "string", + "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." + }, + "streaming": { + "type": "boolean", + "description": "Whether to enable streaming response." } - }, - "description": "Requires `user`. Provide either `message_id` or `text`." + } }, "AppInfoResponse": { "type": "object", "properties": { - "name": { "type": "string" }, - "description": { "type": "string" }, - "tags": { "type": "array", "items": { "type": "string" } } + "name": { + "type": "string", + "description": "Application name." + }, + "description": { + "type": "string", + "description": "Application description." + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Application tags." + }, + "mode": { + "type": "string", + "description": "Application mode. `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for chatflow apps." + }, + "author_name": { + "type": "string", + "description": "Name of the application author." + } } }, "ChatAppParametersResponse": { "type": "object", "properties": { - "opening_statement": { "type": "string" }, - "suggested_questions": { "type": "array", "items": { "type": "string" } }, + "opening_statement": { + "type": "string", + "description": "Opening statement displayed at conversation start." + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of suggested starter questions." + }, "suggested_questions_after_answer": { "type": "object", - "properties": { "enabled": { "type": "boolean" } } + "description": "Configuration for suggested questions after answer.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } }, "speech_to_text": { "type": "object", - "properties": { "enabled": { "type": "boolean" } } + "description": "Speech-to-text configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } }, "text_to_speech": { "type": "object", + "description": "Text-to-speech configuration.", "properties": { - "enabled": { "type": "boolean" }, - "voice": { "type": "string" }, - "language": { "type": "string" }, - "autoPlay": { "type": "string", "enum": ["enabled", "disabled"] } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + }, + "voice": { + "type": "string", + "description": "Voice identifier for TTS." + }, + "language": { + "type": "string", + "description": "Language for TTS." + }, + "autoPlay": { + "type": "string", + "description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play." + } } }, "retriever_resource": { "type": "object", - "properties": { "enabled": { "type": "boolean" } } + "description": "Retriever resource configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } }, "annotation_reply": { "type": "object", - "properties": { "enabled": { "type": "boolean" } } + "description": "Annotation reply configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "more_like_this": { + "type": "object", + "description": "More-like-this configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "Sensitive word avoidance configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } }, "user_input_form": { "type": "array", - "items": { "$ref": "#/components/schemas/UserInputFormItem" } + "description": "List of user input form elements.", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } }, "file_upload": { "type": "object", + "description": "File upload configuration.", "properties": { "image": { "type": "object", + "description": "Image upload settings.", "properties": { - "enabled": { "type": "boolean" }, - "number_limits": { "type": "integer" }, - "detail": {"type": "string"}, - "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } + "enabled": { + "type": "boolean", + "description": "Whether image upload is enabled." + }, + "number_limits": { + "type": "integer", + "description": "Maximum number of images." + }, + "detail": { + "type": "string", + "description": "Image detail level." + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Allowed transfer methods." + } } } } }, "system_parameters": { "type": "object", + "description": "System-level parameters and limits.", "properties": { - "file_size_limit": { "type": "integer" }, - "image_file_size_limit": { "type": "integer" }, - "audio_file_size_limit": { "type": "integer" }, - "video_file_size_limit": { "type": "integer" } + "file_size_limit": { + "type": "integer", + "description": "Maximum file size in MB." + }, + "image_file_size_limit": { + "type": "integer", + "description": "Maximum image file size in MB." + }, + "audio_file_size_limit": { + "type": "integer", + "description": "Maximum audio file size in MB." + }, + "video_file_size_limit": { + "type": "integer", + "description": "Maximum video file size in MB." + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "Maximum number of files for workflow file upload." + } } } } @@ -1825,31 +4023,116 @@ "UserInputFormItem": { "type": "object", "oneOf": [ - { "$ref": "#/components/schemas/TextInputControlWrapper" }, - { "$ref": "#/components/schemas/ParagraphControlWrapper" }, - { "$ref": "#/components/schemas/SelectControlWrapper" } + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } ] }, "TextInputControlWrapper": { - "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } },"required":["text-input"] + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } }, "ParagraphControlWrapper": { - "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } },"required":["paragraph"] + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } }, "SelectControlWrapper": { - "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } },"required":["select"] + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } }, "TextInputControl": { - "type": "object", "required": ["label", "variable", "required"], - "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } + "type": "object", + "description": "Text input form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether input is required." + }, + "default": { + "type": "string", + "description": "Default value." + } + } }, "ParagraphControl": { - "type": "object", "required": ["label", "variable", "required"], - "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } + "type": "object", + "description": "Paragraph (multi-line text) form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether input is required." + }, + "default": { + "type": "string", + "description": "Default value." + } + } }, "SelectControl": { - "type": "object", "required": ["label", "variable", "required", "options"], - "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } } + "type": "object", + "description": "Select (dropdown) form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether selection is required." + }, + "default": { + "type": "string", + "description": "Default selected value." + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of selectable values for this form control." + } + } }, "AppMetaResponse": { "type": "object", @@ -1858,8 +4141,15 @@ "type": "object", "additionalProperties": { "oneOf": [ - { "type": "string", "format": "url", "description": "URL of the icon." }, - { "$ref": "#/components/schemas/ToolIconDetail" } + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "URL of the icon." + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } ] }, "description": "Tool icons. Keys are tool names." @@ -1867,100 +4157,270 @@ } }, "ToolIconDetail": { + "title": "Emoji Icon", "type": "object", + "description": "Detail of a tool icon using emoji.", "properties": { - "background": { "type": "string", "description": "Background color in hex format." }, - "content": { "type": "string", "description": "Emoji content." } + "background": { + "type": "string", + "description": "Background color in hex format." + }, + "content": { + "type": "string", + "description": "Emoji content." + } } }, "WebAppSettingsResponse": { "type": "object", "properties": { - "title": { "type": "string" }, "chat_color_theme": { "type": "string" }, "chat_color_theme_inverted": { "type": "boolean" }, - "icon_type": { "type": "string", "enum": ["emoji", "image"] }, "icon": { "type": "string" }, "icon_background": { "type": "string" }, - "icon_url": { "type": "string", "format": "url", "nullable": true }, "description": { "type": "string" }, "copyright": { "type": "string" }, - "privacy_policy": { "type": "string" }, "custom_disclaimer": { "type": "string" }, "default_language": { "type": "string" }, - "show_workflow_steps": { "type": "boolean" }, "use_icon_as_answer_icon": { "type": "boolean" } + "title": { + "type": "string", + "description": "WebApp title." + }, + "chat_color_theme": { + "type": "string", + "description": "Chat color theme." + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "Whether the chat color theme is inverted." + }, + "icon_type": { + "type": "string", + "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." + }, + "icon": { + "type": "string", + "description": "Icon content (emoji or image ID)." + }, + "icon_background": { + "type": "string", + "description": "Icon background color." + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "URL of the icon image." + }, + "description": { + "type": "string", + "description": "WebApp description." + }, + "copyright": { + "type": "string", + "description": "Copyright text." + }, + "privacy_policy": { + "type": "string", + "description": "Privacy policy URL." + }, + "custom_disclaimer": { + "type": "string", + "description": "Custom disclaimer text." + }, + "default_language": { + "type": "string", + "description": "Default language code." + }, + "show_workflow_steps": { + "type": "boolean", + "description": "Whether to show workflow steps." + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "Whether to use the app icon as the answer icon." + } } }, "AnnotationListResponse": { "type": "object", "properties": { - "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItem" } }, - "has_more": { "type": "boolean" }, - "limit": { "type": "integer" }, - "total": { "type": "integer" }, - "page": { "type": "integer" } + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "description": "List of annotation items for the current page." + }, + "has_more": { + "type": "boolean", + "description": "`true` if more pages are available beyond the current result set." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of annotations matching the query." + }, + "page": { + "type": "integer", + "description": "Current page number." + } } }, "AnnotationItem": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "question": { "type": "string" }, - "answer": { "type": "string" }, - "hit_count": { "type": "integer" }, - "created_at": { "type": "integer", "format": "int64" } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique annotation identifier." + }, + "question": { + "type": "string", + "nullable": true, + "description": "Question text that triggers this annotation." + }, + "answer": { + "type": "string", + "nullable": true, + "description": "Predefined answer returned when the annotation is matched." + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "Number of times this annotation has been matched and returned as a reply." + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Creation timestamp (Unix epoch seconds)." + } } }, "CreateAnnotationRequest": { "type": "object", - "required": ["question", "answer"], + "description": "Request body for creating a new annotation.", + "required": [ + "question", + "answer" + ], "properties": { - "question": { "type": "string" }, - "answer": { "type": "string" } + "question": { + "type": "string", + "description": "Annotation question." + }, + "answer": { + "type": "string", + "description": "Annotation answer." + } } }, "UpdateAnnotationRequest": { "type": "object", - "required": ["question", "answer"], + "description": "Request body for updating an annotation.", + "required": [ + "question", + "answer" + ], "properties": { - "question": { "type": "string" }, - "answer": { "type": "string" } + "question": { + "type": "string", + "description": "Updated annotation question." + }, + "answer": { + "type": "string", + "description": "Updated annotation answer." + } } }, "InitialAnnotationReplySettingsRequest": { "type": "object", - "required": ["score_threshold"], + "description": "Request body for configuring annotation reply settings.", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], "properties": { - "embedding_provider_name": { "type": "string", "description": "Specified embedding model provider name (Optional)." }, - "embedding_model_name": { "type": "string", "description": "Specified embedding model name (Optional)." }, - "score_threshold": { "type": "number", "format": "float", "description": "Similarity threshold for matching annotated replies." } + "embedding_provider_name": { + "type": "string", + "description": "Name of the embedding model provider (e.g., `openai`, `cohere`)." + }, + "embedding_model_name": { + "type": "string", + "description": "Name of the embedding model to use for annotation matching (e.g., `text-embedding-3-small`)." + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "Minimum similarity score for an annotation to be considered a match. Higher values require closer matches.", + "minimum": 0, + "maximum": 1 + } } }, "InitialAnnotationReplySettingsResponse": { "type": "object", "properties": { - "job_id": { "type": "string", "format": "uuid" }, - "job_status": { "type": "string" } + "job_id": { + "type": "string", + "format": "uuid", + "description": "Asynchronous job ID. Use with [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress." + }, + "job_status": { + "type": "string", + "description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed." + } } }, "InitialAnnotationReplySettingsStatusResponse": { "type": "object", "properties": { - "job_id": { "type": "string", "format": "uuid" }, - "job_status": { "type": "string" }, - "error_msg": { "type": "string", "nullable": true } - } - }, - "ErrorResponse": { - "type": "object", - "properties": { - "status": { "type": "integer" }, - "code": { "type": "string" }, - "message": { "type": "string" } + "job_id": { + "type": "string", + "format": "uuid", + "description": "Job ID from the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call." + }, + "job_status": { + "type": "string", + "description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed." + }, + "error_msg": { + "type": "string", + "description": "Error message describing why the job failed. Empty string when `job_status` is not `error`." + } } } } }, "tags": [ - { "name": "Chat", "description": "Operations related to chat messages and interactions." }, - { "name": "Files", "description": "File upload and preview operations." }, - { "name": "End Users", "description": "Operations related to end user information." }, - { "name": "Feedback", "description": "User feedback operations." }, - { "name": "Conversations", "description": "Operations related to managing conversations." }, - { "name": "TTS", "description": "Text-to-Speech and Speech-to-Text operations." }, - { "name": "Application", "description": "Operations to retrieve application settings and information." }, - { "name": "Annotations", "description": "Operations related to managing annotations for direct replies." } + { + "name": "Chats", + "description": "Operations related to chat messages and interactions." + }, + { + "name": "Files", + "description": "File upload and preview operations." + }, + { + "name": "End Users", + "description": "Operations related to end user information." + }, + { + "name": "Feedback", + "description": "User feedback operations." + }, + { + "name": "Conversations", + "description": "Operations related to managing conversations." + }, + { + "name": "TTS", + "description": "Text-to-Speech and Speech-to-Text operations." + }, + { + "name": "Applications", + "description": "Operations to retrieve application settings and information." + }, + { + "name": "Annotations", + "description": "Operations related to managing annotations for direct replies." + } ] } diff --git a/en/api-reference/openapi_chatflow.json b/en/api-reference/openapi_chatflow.json index 04499f1c..4bf1bfa2 100644 --- a/en/api-reference/openapi_chatflow.json +++ b/en/api-reference/openapi_chatflow.json @@ -1,14 +1,14 @@ { "openapi": "3.0.1", "info": { - "title": "Advanced Chat App API", - "description": "Chat applications support session persistence, allowing previous chat history to be used as context for responses. This can be applicable for chatbot, customer service AI, etc. This version includes advanced features like workflow events and more detailed file type support.", + "title": "Chatflow App API", + "description": "Chatflow applications support session persistence, allowing previous chat history to be used as context for responses. Chatflow apps use the `advanced-chat` mode, providing workflow-level streaming events for detailed execution tracking including node starts, finishes, iterations, and workflow lifecycle.", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "The base URL for the Advanced Chat App API. Replace {api_base_url} with the actual API base URL provided for your application (e.g., from props.appDetail.api_base_url).", + "description": "The base URL for the Chatflow App API. Replace {api_base_url} with the actual API base URL provided for your application.", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", @@ -26,34 +26,47 @@ "/chat-messages": { "post": { "summary": "Send Chat Message", - "description": "Send a request to the advanced chat application, supporting various file types and workflow events.", + "description": "Send a request to the chat application.", "operationId": "sendAdvancedChatMessage", - "tags": ["Chatflow"], + "tags": [ + "Chats" + ], "requestBody": { - "description": "Request body to send an advanced chat message.", + "description": "Request body to send a chat message.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdvancedChatRequest" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file_and_workflow": { - "summary": "Streaming mode example with image file", + "streaming_example": { + "summary": "Request Example - Streaming mode", "value": { - "inputs": {"user_name": "Alice"}, - "query": "Analyze this document and tell me its sentiment.", + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "conv_12345", - "user": "user_alice", + "conversation_id": "", + "user": "abc-123", "files": [ { - "type": "document", + "type": "image", "transfer_method": "remote_url", - "url": "https://example.com/mydoc.pdf" + "url": "https://cloud.dify.ai/logo/logo-site.png" } - ], - "auto_generate_name": true + ] + } + }, + "blocking_example": { + "summary": "Request Example - Blocking mode", + "value": { + "inputs": {}, + "query": "What are the specs of the iPhone 13 Pro Max?", + "response_mode": "blocking", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "user": "abc-123" } } } @@ -62,39 +75,417 @@ }, "responses": { "200": { - "description": "Successful response. The content type and structure depend on the `response_mode`.\n- `blocking`: `application/json` with `ChatCompletionResponse`.\n- `streaming`: `text/event-stream` with `ChunkAdvancedChatEvent` stream.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkChatEvent` objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "Response Example - Blocking mode", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "advanced-chat", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "A stream of Server-Sent Events. See `ChunkAdvancedChatEvent` for structures." + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkChatEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. `message_end` marks the end of the chat message, but the stream may continue with workflow lifecycle events such as `workflow_finished` or `workflow_paused`. The stream ends when a terminal workflow event is received, or when an `error` event terminates the stream. Ignore `ping` events (sent every 10 seconds to keep the connection alive). Note that the HTTP status code is always `200` even when an error event occurs within the stream." }, "examples": { - "workflow_events_example": { - "summary": "Example stream including workflow events", - "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task_abc\", \"workflow_run_id\": \"wf_run_1\", \"data\": {\"id\": \"wf_run_1\", \"workflow_id\": \"wf_def_xyz\", \"sequence_number\": 1, \"created_at\": 1705395332}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"task_abc\", \"workflow_run_id\": \"wf_run_1\", \"data\": {\"id\": \"node_run_1\", \"node_id\": \"node_start\", \"node_type\": \"start\", \"title\": \"Start Node\", \"index\": 0, \"inputs\": {}, \"created_at\": 1705395333}}\n\ndata: {\"event\": \"message\", \"task_id\": \"task_abc\", \"message_id\": \"msg_123\", \"conversation_id\": \"conv_123\", \"answer\": \"Processing... \", \"created_at\": 1705395334}\n\ndata: {\"event\": \"node_finished\", \"task_id\": \"task_abc\", \"workflow_run_id\": \"wf_run_1\", \"data\": {\"id\": \"node_run_1\", \"node_id\": \"node_start\", \"node_type\": \"start\", \"title\": \"Start Node\", \"index\": 0, \"status\": \"succeeded\", \"elapsed_time\": 0.5, \"created_at\": 1705395333}}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"task_abc\", \"message_id\": \"msg_123\", \"conversation_id\": \"conv_123\", \"metadata\": {\"usage\": {\"total_tokens\": 10}}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"task_abc\", \"workflow_run_id\": \"wf_run_1\", \"data\": {\"id\": \"wf_run_1\", \"workflow_id\": \"wf_def_xyz\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705395332, \"finished_at\": 1705395335}}\n\n" - } + "streamingResponseBasic": { + "summary": "Response Example - Streaming (Basic)", + "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" + }, + "streamingResponseWorkflow": { + "summary": "Response Example - Streaming (Workflow)", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}" + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestGeneric" }, - "404": { "$ref": "#/components/responses/ConversationNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.\n- `bad_request` : Cannot use draft workflow version.\n- `bad_request` : Invalid `workflow_id` format.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "conversation_completed": { + "summary": "conversation_completed", + "value": { + "status": 400, + "code": "conversation_completed", + "message": "The conversation has ended. Please start a new conversation." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "is_draft_workflow": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. " + } + }, + "workflow_id_format_error": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Invalid workflow_id format: 'not-a-valid-id'. " + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Conversation does not exist.\n- `not_found` : Workflow not found with the specified `workflow_id`.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "workflow_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab" + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/chat-messages/{task_id}/stop": { + "post": { + "summary": "Stop Chat Message Generation", + "description": "Stops a chat message generation task. Only supported in `streaming` mode.", + "operationId": "stopAdvancedChatMessageGeneration", + "tags": [ + "Chats" + ], + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "description": "Task ID, can be obtained from the streaming chunk return of the [Send Chat Message](/api-reference/chats/send-chat-message) API.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "user" + ], + "properties": { + "user": { + "type": "string", + "description": "User identifier, must be consistent with the user passed in the send message interface." + } + } + }, + "examples": { + "example": { + "summary": "Request Example", + "value": { + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + } + } + } + }, + "/messages/{message_id}/suggested": { + "get": { + "summary": "Get Next Suggested Questions", + "description": "Get next questions suggestions for the current message.", + "operationId": "getAdvancedSuggestedQuestions", + "tags": [ + "Chats" + ], + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "Message ID.", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": true, + "description": "User identifier.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved suggested questions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuggestedQuestionsResponse" + }, + "examples": { + "suggestedQuestions": { + "summary": "Response Example", + "value": { + "result": "success", + "data": [ + "What colors does the iPhone 13 Pro Max come in?", + "How does the battery compare to iPhone 12?", + "What is the price range?" + ] + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Suggested questions feature is disabled.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Suggested Questions Is Disabled." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Message does not exist.", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } } } }, "/files/upload": { "post": { - "summary": "File Upload", - "description": "Upload a file for use when sending messages, enabling multimodal understanding. Supports any formats supported by your application. Uploaded files are for use by the current end-user only.", "operationId": "uploadAdvancedChatFile", - "tags": ["Files"], + "tags": [ + "Files" + ], + "summary": "Upload File", + "description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", "requestBody": { "description": "File upload request. Requires multipart/form-data.", "required": true, @@ -102,16 +493,18 @@ "multipart/form-data": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "file" + ], "properties": { "file": { "type": "string", "format": "binary", - "description": "The file to be uploaded." + "description": "The file to be uploaded. Supported types include images, documents, audio, and video." }, "user": { "type": "string", - "description": "User identifier, unique within the application. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "description": "User identifier, defined by the developer's rules, must be unique within the application." } } } @@ -119,65 +512,121 @@ } }, "responses": { - "200": { + "201": { "description": "File uploaded successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestFile" }, - "413": { "$ref": "#/components/responses/FileTooLarge" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFile" }, - "503": { "$ref": "#/components/responses/S3ErrorFile" }, - "500": { "$ref": "#/components/responses/InternalServerError" } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "Get End User", - "description": "Retrieve an end user by ID.\n\nThis is useful when other APIs return an end-user ID (e.g. `created_by` from File Upload).", - "operationId": "getEndUserChatflow", - "tags": ["End Users"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "End user ID.", - "schema": { "type": "string", "format": "uuid" } - } - ], - "responses": { - "200": { - "description": "End user retrieved successfully.", + "400": { + "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetail" } + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } + "413": { + "description": "`file_too_large` : File size exceeded.", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } } } }, "/files/{file_id}/preview": { "get": { - "summary": "File Preview", - "description": "Preview or download uploaded files. This endpoint allows you to access files that have been previously uploaded via the File Upload API. Files can only be accessed if they belong to messages within the requesting application.", "operationId": "previewChatFlowFile", - "tags": ["Files"], + "tags": [ + "Files" + ], + "summary": "Download File", + "description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", "parameters": [ { "name": "file_id", "in": "path", "required": true, - "description": "The unique identifier of the file to preview, obtained from the File Upload API response.", + "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.", "schema": { "type": "string", "format": "uuid" @@ -187,131 +636,156 @@ "name": "as_attachment", "in": "query", "required": false, - "description": "Whether to force download the file as an attachment. Default is `false` (preview in browser).", + "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", "schema": { "type": "boolean", "default": false } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier, used for end-user context.", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "File content returned successfully. Headers set based on file type and request parameters.", + "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", "content": { - "image/png": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } - }, - "headers": { - "Content-Type": { - "description": "MIME type of the file", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "File size in bytes (if available)", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "Set to 'attachment' if as_attachment=true", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "Caching headers for performance", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "Set to 'bytes' for audio/video files", - "schema": { - "type": "string", - "example": "bytes" - } - } - } - }, - "400": { - "description": "Bad Request. Possible error codes:\n- `invalid_param`: Abnormal parameter input.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } } }, "403": { - "description": "Forbidden. Possible error codes:\n- `file_access_denied`: File access denied or file does not belong to current application.", + "description": "`file_access_denied` : Access to the requested file is denied.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } } } }, "404": { - "description": "Not Found. Possible error codes:\n- `file_not_found`: File not found or has been deleted.", + "description": "`file_not_found` : The requested file was not found.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "500": { - "description": "Internal server error.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } } } } } } }, - "/chat-messages/{task_id}/stop": { - "post": { - "summary": "Stop Advanced Chat Message Generation", - "description": "Stops an advanced chat message generation task. Only supported in streaming mode.", - "operationId": "stopAdvancedChatMessageGeneration", - "tags": ["Chatflow"], + "/end-users/{end_user_id}": { + "get": { + "operationId": "getEndUserChatflow", + "tags": [ + "End Users" + ], + "summary": "Get End User Info", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).", "parameters": [ { - "name": "task_id", + "name": "end_user_id", "in": "path", "required": true, - "description": "Task ID from the streaming chunk.", - "schema": { "type": "string" } + "description": "End user ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "End user retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "Response Example", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : End user not found.", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/messages/{message_id}/feedbacks": { + "post": { + "operationId": "postAdvancedChatMessageFeedback", + "tags": [ + "Feedback" + ], + "summary": "Submit Message Feedback", + "description": "Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.", + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "Message ID.", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -319,12 +793,15 @@ "content": { "application/json": { "schema": { - "type": "object", - "required": ["user"], - "properties": { - "user": { - "type": "string", - "description": "User identifier, consistent with the send message call. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "Request Example", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" } } } @@ -332,111 +809,105 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "Message Feedback", - "description": "Provide feedback for a message.", - "operationId": "postAdvancedChatMessageFeedback", - "tags": ["Feedback"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "Message ID.", - "schema": { "type": "string" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequest" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : Message does not exist.", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } } } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } } } }, "/app/feedbacks": { "get": { - "summary": "Get feedbacks of application", - "description": "Get application's feedbacks.", "operationId": "getAdvancedChatAppFeedbacks", - "tags": ["Feedback"], + "tags": [ + "Feedback" + ], + "summary": "List App Feedbacks", + "description": "Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.", "parameters": [ - { "$ref": "#/components/parameters/PageQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParam" } + { + "name": "page", + "in": "query", + "description": "Page number for pagination.", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of records per page.", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } + } ], "responses": { "200": { "description": "A list of application feedbacks.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponse" } - } - } - } - } - } - }, - "/messages/{message_id}/suggested": { - "get": { - "summary": "Next Suggested Questions", - "description": "Get next questions suggestions for the current message.", - "operationId": "getAdvancedSuggestedQuestions", - "tags": ["Chatflow"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "Message ID.", - "schema": { "type": "string" } - }, - { "$ref": "#/components/parameters/UserQueryParam" } - ], - "responses": { - "200": { - "description": "Successfully retrieved suggested questions.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponse" } - } - } - } - } - } - }, - "/messages": { - "get": { - "summary": "Get Conversation History Messages", - "description": "Returns historical chat records in a scrolling load format.", - "operationId": "getAdvancedConversationHistory", - "tags": ["Conversations"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdQueryParam" }, - { "$ref": "#/components/parameters/UserQueryParam" }, - { - "name": "first_id", - "in": "query", - "description": "ID of the first chat record on the current page (for pagination).", - "schema": { "type": "string" } - }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20" } - ], - "responses": { - "200": { - "description": "Successfully retrieved conversation history.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationHistoryResponse" } + "schema": { + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "rating": "like", + "content": "The response accurately answered my question about product specifications.", + "from_source": "user", + "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "from_account_id": null, + "created_at": "2025-01-16T14:30:29Z", + "updated_at": "2025-01-16T14:30:29Z" + }, + { + "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", + "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", + "rating": "dislike", + "content": "The answer was too vague and did not address the specific pricing question.", + "from_source": "user", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", + "from_account_id": null, + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" + } + ] + } + } + } } } } @@ -445,22 +916,616 @@ }, "/conversations": { "get": { - "summary": "Get Conversations", - "description": "Retrieve the conversation list for the current user.", + "summary": "List Conversations", + "description": "Retrieve the conversation list for the current user, ordered by most recently active.", "operationId": "getAdvancedConversationsList", - "tags": ["Conversations"], + "tags": [ + "Conversations" + ], "parameters": [ - { "$ref": "#/components/parameters/UserQueryParam" }, - { "$ref": "#/components/parameters/LastIdQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100" }, - { "$ref": "#/components/parameters/SortByQueryParam" } + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier.", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "The ID of the last record on the current page (for pagination).", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of records to return.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "sort_by", + "in": "query", + "required": false, + "description": "Sorting field. Use '-' prefix for descending order.", + "schema": { + "type": "string", + "enum": [ + "created_at", + "-created_at", + "updated_at", + "-updated_at" + ], + "default": "-updated_at" + } + } ], "responses": { "200": { "description": "Successfully retrieved conversations list.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationsListResponse" } + "schema": { + "$ref": "#/components/schemas/ConversationsListResponse" + }, + "examples": { + "conversationsList": { + "summary": "Response Example", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Last conversation does not exist (invalid `last_id`).", + "content": { + "application/json": { + "examples": { + "last_conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Last Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/messages": { + "get": { + "summary": "List Conversation Messages", + "description": "Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order.", + "operationId": "getAdvancedConversationHistory", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier.", + "schema": { + "type": "string" + } + }, + { + "name": "first_id", + "in": "query", + "required": false, + "description": "The ID of the first chat record on the current page. Default is `null` (fetches the latest messages). For subsequent pages, use the ID of the first message from the current list to get older messages.", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of chat history messages to return per request.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved conversation history.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "Response Example", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "parent_message_id": null, + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "status": "normal", + "error": null, + "message_files": [], + "feedback": { + "rating": "like" + }, + "retriever_resources": [], + "agent_thoughts": [], + "created_at": 1705407629 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Conversation does not exist.\n- `not_found` : First message does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "first_message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "First Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables": { + "get": { + "summary": "List Conversation Variables", + "description": "Retrieve variables from a specific conversation.", + "operationId": "getAdvancedConversationVariables", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "The user identifier.", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "The ID of the last record on the current page (for pagination).", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of records to return.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "variable_name", + "in": "query", + "required": false, + "description": "Filter variables by a specific name.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved conversation variables.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariablesResponse" + }, + "examples": { + "conversationVariables": { + "summary": "Response Example", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "dark_mode", + "description": "User preference setting", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Conversation does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/name": { + "post": { + "summary": "Rename Conversation", + "description": "Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations.", + "operationId": "renameAdvancedConversation", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationRenameRequest" + }, + "examples": { + "renameExample": { + "summary": "Request Example", + "value": { + "name": "iPhone Specs Chat", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Conversation renamed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationListItem" + }, + "examples": { + "renamedConversation": { + "summary": "Response Example", + "value": { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Conversation does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables/{variable_id}": { + "put": { + "summary": "Update Conversation Variable", + "description": "Update the value of a specific conversation variable. The value must match the expected type.", + "operationId": "updateChatflowConversationVariable", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "variable_id", + "in": "path", + "required": true, + "description": "Variable ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableUpdateRequest" + }, + "examples": { + "updateStringVariable": { + "summary": "Request Example", + "value": { + "value": "new value", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Variable updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableItem" + }, + "examples": { + "updatedVariable": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "new value", + "description": "User preference setting", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Variable value type mismatch.", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "type_mismatch": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Value type mismatch: expected string, got integer." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Conversation does not exist.\n- `not_found` : Conversation variable does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "variable_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Variable Not Exists." + } + } + } } } } @@ -472,94 +1537,100 @@ "summary": "Delete Conversation", "description": "Delete a conversation.", "operationId": "deleteAdvancedConversation", - "tags": ["Conversations"], + "tags": [ + "Conversations" + ], "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParam" } + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + } ], "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { "type": "object", - "required": ["user"], "properties": { - "user": { "type": "string", "description": "The user identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." } + "user": { + "type": "string", + "description": "The user identifier." + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "Request Example" } } } } }, "responses": { - "204": { "description": "Conversation deleted successfully. No Content." } - } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "Conversation Rename", - "description": "Rename the session.", - "operationId": "renameAdvancedConversation", - "tags": ["Conversations"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParam" } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationRenameRequest" } - } - } - }, - "responses": { - "200": { - "description": "Conversation renamed successfully.", + "204": { + "description": "Conversation deleted successfully. No content returned." + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationRenameResponse" } - } - } - } - } - } - }, - "/conversations/{conversation_id}/variables": { - "get": { - "summary": "Get Conversation Variables", - "description": "Retrieve variables from a specific conversation.", - "operationId": "getAdvancedConversationVariables", - "tags": ["Conversations"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParam" }, - { "$ref": "#/components/parameters/UserQueryParam" }, - { "$ref": "#/components/parameters/LastIdQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100" } - ], - "responses": { - "200": { - "description": "Successfully retrieved conversation variables.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationVariablesResponse" } + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } } } }, - "404": { "$ref": "#/components/responses/ConversationNotFound" } + "404": { + "description": "`not_found` : Conversation does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } } } }, "/audio-to-text": { "post": { - "summary": "Speech to Text", - "description": "Convert audio file to text. Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm. File size limit: 15MB.", "operationId": "advancedAudioToText", - "tags": ["TTS"], + "tags": [ + "TTS" + ], + "summary": "Convert Audio to Text", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", "requestBody": { "required": true, "content": { "multipart/form-data": { - "schema": { "$ref": "#/components/schemas/AudioToTextRequest" } + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } } } }, @@ -568,7 +1639,133 @@ "description": "Successfully converted audio to text.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AudioToTextResponse" } + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "Response Example", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : Audio file size exceeded the limit.", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : Audio type is not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -577,28 +1774,108 @@ }, "/text-to-audio": { "post": { - "summary": "Text to Audio", - "description": "Convert text to speech.", "operationId": "advancedTextToAudio", - "tags": ["TTS"], + "tags": [ + "TTS" + ], + "summary": "Convert Text to Audio", + "description": "Convert text to speech.", "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/TextToAudioJsonRequest" } + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "Request Example", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } } } }, "responses": { "200": { - "description": "Audio file generated successfully.", + "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", "content": { - "audio/wav": { "schema": { "type": "string", "format": "binary" } }, - "audio/mp3": { "schema": { "type": "string", "format": "binary" } } - }, - "headers": { - "Content-Type": { - "schema": { "type": "string", "example": "audio/wav" } + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -607,15 +1884,35 @@ }, "/info": { "get": { - "summary": "Get Application Basic Information", "operationId": "getAdvancedChatAppInfo", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App Info", + "description": "Retrieve basic information about this application, including name, description, tags, and mode.", "responses": { "200": { - "description": "Basic application information.", + "description": "Basic information of the application.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppInfoResponse" } + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "Response Example", + "value": { + "name": "My Chatflow App", + "description": "A helpful customer service chatbot.", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "advanced-chat", + "author_name": "Dify Team" + } + } + } } } } @@ -624,15 +1921,101 @@ }, "/parameters": { "get": { - "summary": "Get Application Parameters Information", "operationId": "getAdvancedChatAppParameters", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App Parameters", + "description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.", "responses": { "200": { - "description": "Application parameters.", + "description": "Application parameters information.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ChatAppParametersResponse" } + "schema": { + "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "Response Example", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : App unavailable or misconfigured.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } } } } @@ -641,15 +2024,34 @@ }, "/meta": { "get": { - "summary": "Get Application Meta Information", "operationId": "getAdvancedChatAppMeta", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App Meta", + "description": "Retrieve metadata about this application, including tool icons and other configuration details.", "responses": { "200": { - "description": "Application meta information (tool icons).", + "description": "Successfully retrieved application meta information.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppMetaResponse" } + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "Response Example", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } } } } @@ -658,15 +2060,58 @@ }, "/site": { "get": { - "summary": "Get Application WebApp Settings", "operationId": "getAdvancedChatWebAppSettings", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App WebApp Settings", + "description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.", "responses": { "200": { - "description": "WebApp settings.", + "description": "WebApp settings of the application.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" } + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "Response Example", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "A helpful customer service chatbot.", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Site not found for this application or the workspace has been archived.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } } } } @@ -674,94 +2119,652 @@ } }, "/apps/annotations": { - "get": { - "summary": "Get Annotation List", - "operationId": "getAdvancedAnnotationList", - "tags": ["Annotations"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100" } + "post": { + "summary": "Create Annotation", + "description": "Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response.", + "operationId": "createAdvancedAnnotation", + "tags": [ + "Annotations" ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAnnotationRequest" + }, + "examples": { + "createAnnotation": { + "summary": "Request Example", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform." + } + } + } + } + } + }, "responses": { - "200": { - "description": "Annotation list.", + "201": { + "description": "Annotation created successfully.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AnnotationListResponse" } + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "createdAnnotation": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 0, + "created_at": 1705407629 + } + } + } } } } } }, - "post": { - "summary": "Create Annotation", - "operationId": "createAdvancedAnnotation", - "tags": ["Annotations"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" } + "get": { + "summary": "List Annotations", + "description": "Retrieves a paginated list of annotations for the application. Supports keyword search filtering.", + "operationId": "getAdvancedAnnotationList", + "tags": [ + "Annotations" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "Page number for pagination.", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of items per page.", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "keyword", + "in": "query", + "description": "Keyword to filter annotations by question or answer content.", + "required": false, + "schema": { + "type": "string" } } - }, + ], "responses": { - "200": { "description": "Annotation created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } }, - "201": { "description": "Annotation created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } } + "200": { + "description": "Successfully retrieved annotation list.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationListResponse" + }, + "examples": { + "annotationList": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 5, + "created_at": 1705407629 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + } } } }, "/apps/annotations/{annotation_id}": { "put": { "summary": "Update Annotation", + "description": "Updates the question and answer of an existing annotation.", "operationId": "updateAdvancedAnnotation", - "tags": ["Annotations"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParam" } ], + "tags": [ + "Annotations" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "The unique identifier of the annotation to update.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], "requestBody": { "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" } } } + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateAnnotationRequest" + }, + "examples": { + "updateAnnotation": { + "summary": "Request Example", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." + } + } + } + } + } }, "responses": { - "200": { "description": "Annotation updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } } + "200": { + "description": "Annotation updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "updatedAnnotation": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", + "hit_count": 5, + "created_at": 1705407629 + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Insufficient permissions to edit annotations.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Annotation does not exist.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } } }, "delete": { "summary": "Delete Annotation", + "description": "Deletes an annotation and its associated hit history.", "operationId": "deleteAdvancedAnnotation", - "tags": ["Annotations"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParam" } ], + "tags": [ + "Annotations" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "The unique identifier of the annotation to delete.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], "responses": { - "204": { "description": "Annotation deleted." } + "204": { + "description": "Annotation deleted successfully." + }, + "403": { + "description": "`forbidden` : Insufficient permissions to edit annotations.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Annotation does not exist.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } } } }, "/apps/annotation-reply/{action}": { "post": { - "summary": "Initial Annotation Reply Settings", + "summary": "Configure Annotation Reply", + "description": "Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.", "operationId": "initialAdvancedAnnotationReplySettings", - "tags": ["Annotations"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationActionPathParam" } ], + "tags": [ + "Annotations" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "Action to perform.", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + } + ], "requestBody": { "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" } } } + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" + }, + "examples": { + "enableAnnotationReply": { + "summary": "Request Example", + "value": { + "score_threshold": 0.9, + "embedding_provider_name": "openai", + "embedding_model_name": "text-embedding-3-small" + } + } + } + } + } }, "responses": { - "200": { "description": "Task initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" } } } }, - "202": { "description": "Task accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" } } } } + "200": { + "description": "Annotation reply settings task initiated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" + }, + "examples": { + "annotationReplyResponse": { + "summary": "Response Example", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "waiting" + } + } + } + } + } + } } } }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { - "summary": "Query Initial Annotation Reply Settings Task Status", + "summary": "Get Annotation Reply Job Status", + "description": "Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", "operationId": "getAdvancedInitialAnnotationReplySettingsStatus", - "tags": ["Annotations"], + "tags": [ + "Annotations" + ], "parameters": [ - { "$ref": "#/components/parameters/AnnotationActionPathParam" }, - { "$ref": "#/components/parameters/JobIdPathParam" } + { + "name": "action", + "in": "path", + "required": true, + "description": "Action type, must match the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call.", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "Job ID returned by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", + "schema": { + "type": "string", + "format": "uuid" + } + } ], "responses": { - "200": { "description": "Task status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" } } } } + "200": { + "description": "Successfully retrieved task status.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "Response Example", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : The specified job does not exist.", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "The job does not exist." + } + } + } + } + } + } + } + } + }, + "/workflows/run/{workflow_run_id}": { + "get": { + "summary": "Get Workflow Run Detail", + "description": "Retrieve the current execution results of a workflow task based on the workflow execution ID.", + "operationId": "getChatflowWorkflowRunDetail", + "tags": [ + "Workflow Runs" + ], + "parameters": [ + { + "name": "workflow_run_id", + "in": "path", + "required": true, + "description": "Workflow run ID, can be obtained from the streaming events or message metadata.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved workflow run details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "Response Example", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } + } + } + }, + "400": { + "description": "`not_workflow_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Workflow run not found.", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } + } + } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "List Workflow Logs", + "description": "Retrieve paginated workflow execution logs with filtering options.", + "operationId": "listChatflowWorkflowLogs", + "tags": [ + "Workflow Runs" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "Keyword to search in logs.", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "Filter by execution status.", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "Page number for pagination.", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of items per page.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "Filter logs created before this ISO 8601 timestamp.", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "Filter logs created after this ISO 8601 timestamp.", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "Filter by end user session ID.", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "Filter by account ID.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved workflow logs.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "Response Example", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0 + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_chatflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } } } } @@ -772,413 +2775,3433 @@ "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", - "description": "API Key authentication." + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" } }, - "parameters": { - "PageQueryParam": { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParam": { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer" } }, - "LimitQueryParamDefault20": { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100": { "name": "limit", "in": "query", "description": "Number of items per page (Default 20, Max 100).", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParam": { "name": "user", "in": "query", "required": true, "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface.", "schema": { "type": "string" } }, - "ConversationIdQueryParam": { "name": "conversation_id", "in": "query", "required": true, "description": "Conversation ID.", "schema": { "type": "string" } }, - "LastIdQueryParam": { "name": "last_id", "in": "query", "description": "ID of the last record for pagination.", "schema": { "type": "string" } }, - "SortByQueryParam": { "name": "sort_by", "in": "query", "description": "Sorting field (e.g., -updated_at).", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParam": { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID.", "schema": { "type": "string" } }, - "AnnotationIdPathParam": { "name": "annotation_id", "in": "path", "required": true, "description": "Annotation ID.", "schema": { "type": "string", "format": "uuid" } }, - "AnnotationActionPathParam": { "name": "action", "in": "path", "required": true, "description": "Action: 'enable' or 'disable'.", "schema": { "type": "string", "enum": ["enable", "disable"] } }, - "JobIdPathParam": { "name": "job_id", "in": "path", "required": true, "description": "Job ID.", "schema": { "type": "string", "format": "uuid" } } - }, "responses": { - "BadRequestGeneric": { "description": "Bad Request. Check parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "BadRequestFile": { "description": "Bad Request for file operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "FileTooLarge": { "description": "File is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "UnsupportedFileTypeFile": { "description": "Unsupported file type for upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "S3ErrorFile": { "description": "S3 storage error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "InternalServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "SuccessResult": { "description": "Operation successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFound": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "EndUserNotFound": { "description": "End user not found. Error code: `end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } + "SuccessResult": { + "description": "Operation successful.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Result status." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "AdvancedChatRequest": { + "ChatRequest": { "type": "object", - "required": ["query", "user"], + "required": [ + "inputs", + "query", + "user" + ], "properties": { - "query": { "type": "string", "description": "User input/question content." }, + "query": { + "type": "string", + "description": "User input/question content." + }, "inputs": { "type": "object", - "description": "Key/value pairs for app variables. For file type variables, value should be an InputFileObject.", - "additionalProperties": { - "oneOf": [ - { "type": "string" }, - { "type": "number" }, - { "type": "boolean" }, - { "$ref": "#/components/schemas/InputFileObjectAdvanced" } - ] - }, - "default": {} + "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", + "additionalProperties": true + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior." + }, + "user": { + "type": "string", + "description": "User identifier, unique within the application. This identifier scopes data access — conversations, messages, and files are only visible when queried with the same `user` value." + }, + "conversation_id": { + "type": "string", + "description": "Conversation ID to continue a conversation. Pass the previous message's `conversation_id`. To start a new conversation, omit this field or pass an empty string. The response will return a `conversation_id` — pass it in subsequent messages to continue that conversation." }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "Response mode. Cloudflare timeout is 100s for blocking." }, - "user": { "type": "string", "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." }, - "conversation_id": { "type": "string", "description": "Conversation ID to continue." }, "files": { "type": "array", - "items": { "$ref": "#/components/schemas/InputFileObjectAdvanced" }, - "description": "List of files for Vision-capable models or general file input." + "description": "File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`.", + "items": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "File type." + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file." + }, + "url": { + "type": "string", + "format": "url", + "description": "File URL (required when `transfer_method` is `remote_url`)." + }, + "upload_file_id": { + "type": "string", + "description": "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`)." + } + } + } }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "Auto-generate conversation title." } - } - }, - "InputFileObjectAdvanced": { - "type": "object", - "required": ["type", "transfer_method"], - "properties": { - "type": { + "auto_generate_name": { + "type": "boolean", + "description": "Auto-generate conversation title. If `false`, use the [Rename Conversation](/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation.", + "default": true + }, + "workflow_id": { "type": "string", - "enum": ["document", "image", "audio", "video", "custom"], - "description": "Type of the file. 'document' covers TXT, MD, PDF, HTML, XLSX, DOCX, CSV, EML, MSG, PPTX, XML, EPUB. 'image' covers JPG, PNG, GIF, WEBP, SVG. 'audio' covers MP3, M4A, WAV, WEBM, AMR. 'video' covers MP4, MOV, MPEG, MPGA." - }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "Transfer method, `remote_url` for file URL / `local_file` for file upload" }, - "url": { "type": "string", "format": "url", "description": "File URL (when the transfer method is `remote_url`)" }, - "upload_file_id": { "type": "string", "description": "Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`)" } - }, - "anyOf": [ - { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } - }, - { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "description": "Specify a published workflow version ID to execute. If not provided, the latest published version is used." } - ], - "example": { "type": "image", "transfer_method": "remote_url", "url": "https://example.com/image.png" } + } }, "ChatCompletionResponse": { "type": "object", - "description": "Response for blocking mode chat.", "properties": { - "event": { "type": "string", "example": "message" }, - "task_id": { "type": "string", "format": "uuid" }, - "id": { "type": "string", "format": "uuid", "description": "Unique ID of this response event." }, - "message_id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "mode": { "type": "string", "example": "chat" }, - "answer": { "type": "string" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadata" }, - "created_at": { "type": "integer", "format": "int64" } + "event": { + "type": "string", + "description": "Event type, fixed as `message`." + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID for request tracking and stop response API." + }, + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of this response event." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "mode": { + "type": "string", + "description": "App mode, fixed as `advanced-chat`." + }, + "answer": { + "type": "string", + "description": "Complete response content." + }, + "metadata": { + "type": "object", + "description": "Metadata including usage and retriever resources.", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Message creation timestamp (Unix epoch seconds)." + } } }, - "ResponseMetadata": { + "ChunkChatEvent": { "type": "object", + "description": "Base schema for Server-Sent Event chunks in streaming mode.", "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, - "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResource" } } - } - }, - "ChunkAdvancedChatEvent": { - "type": "object", - "required": ["event"], - "properties": { - "event": { "type": "string", "enum": ["message", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "workflow_started", "node_started", "node_finished", "workflow_finished", "error", "ping"] } + "event": { + "type": "string", + "description": "The type of event.", + "enum": [ + "message", + "tts_message", + "tts_message_end", + "message_file", + "message_end", + "message_replace", + "workflow_started", + "workflow_finished", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "workflow_paused", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "agent_log", + "text_chunk", + "text_replace", + "error", + "ping" + ] + } }, "discriminator": { "propertyName": "event", "mapping": { - "message": "#/components/schemas/StreamEventAdvChatMessage", - "message_file": "#/components/schemas/StreamEventAdvMessageFile", - "message_end": "#/components/schemas/StreamEventAdvMessageEnd", - "tts_message": "#/components/schemas/StreamEventAdvTtsMessage", - "tts_message_end": "#/components/schemas/StreamEventAdvTtsMessageEnd", - "message_replace": "#/components/schemas/StreamEventAdvMessageReplace", - "workflow_started": "#/components/schemas/StreamEventAdvWorkflowStarted", - "node_started": "#/components/schemas/StreamEventAdvNodeStarted", - "node_finished": "#/components/schemas/StreamEventAdvNodeFinished", - "workflow_finished": "#/components/schemas/StreamEventAdvWorkflowFinished", - "error": "#/components/schemas/StreamEventAdvError", - "ping": "#/components/schemas/StreamEventAdvPing" + "message": "#/components/schemas/StreamEventChatMessage", + "tts_message": "#/components/schemas/StreamEventChatTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", + "message_file": "#/components/schemas/StreamEventChatMessageFile", + "message_end": "#/components/schemas/StreamEventChatMessageEnd", + "message_replace": "#/components/schemas/StreamEventChatMessageReplace", + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "text_chunk": "#/components/schemas/StreamEventChatTextChunk", + "text_replace": "#/components/schemas/StreamEventChatTextReplace", + "error": "#/components/schemas/StreamEventChatError", + "ping": "#/components/schemas/StreamEventChatPing" } } }, - "StreamEventBaseAdv": { + "StreamEventBase": { "type": "object", + "description": "Base properties for stream events.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "message_id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "created_at": { "type": "integer", "format": "int64" } + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + } } }, - "StreamEventAdvChatMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string" } } } ] - }, - "StreamEventAdvMessageFile": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], + "StreamEventChatMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "type": { "type": "string", "description": "File type, e.g., 'image'." }, - "belongs_to": { "type": "string", "enum": ["assistant"] }, - "url": { "type": "string", "format": "url" }, - "conversation_id": { "type": "string", "format": "uuid" } + "answer": { + "type": "string", + "description": "LLM returned text chunk." + } } } ] }, - "StreamEventAdvMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } } } ] - }, - "StreamEventAdvTtsMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 encoded audio." } } } - ] - }, - "StreamEventAdvTtsMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "Empty string." } } } - ] - }, - "StreamEventAdvMessageReplace": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "Replacement content." } } } - ] - }, - "StreamEventAdvWorkflowStarted": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "workflow_run_id", "data"], + "StreamEventChatTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS audio stream event (base64 encoded Mp3). Available if auto-play enabled.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/WorkflowStartedData" } + "audio": { + "type": "string", + "format": "byte", + "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." + } } } ] }, - "WorkflowStartedData": { - "type": "object", "required": ["id", "workflow_id", "sequence_number", "created_at"], - "properties": { - "id": { "type": "string", "format": "uuid" }, - "workflow_id": { "type": "string", "format": "uuid" }, - "sequence_number": { "type": "integer" }, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "StreamEventAdvNodeStarted": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "workflow_run_id", "data"], + "StreamEventChatTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS audio stream end event.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/NodeStartedData" } + "audio": { + "type": "string", + "description": "Empty string. Signals the end of the audio stream." + } } } ] }, - "NodeStartedData": { - "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], - "properties": { - "id": { "type": "string", "format": "uuid", "description": "Unique ID of this node execution instance." }, - "node_id": { "type": "string", "format": "uuid", "description": "ID of the node definition." }, - "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer" }, - "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true }, - "inputs": { "type": "object", "additionalProperties": true, "description": "Variables used by the node." }, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "StreamEventAdvNodeFinished": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "workflow_run_id", "data"], + "StreamEventChatMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "Message file event, a new file created by a tool.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/NodeFinishedData" } + "id": { + "type": "string", + "format": "uuid", + "description": "File unique ID." + }, + "type": { + "type": "string", + "description": "File type, e.g. `image`." + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "Who this file belongs to, always `assistant` here." + }, + "url": { + "type": "string", + "format": "url", + "description": "Remote URL of the file." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + } } } ] }, - "NodeFinishedData": { - "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "status", "created_at"], - "properties": { - "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "format": "uuid" }, - "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer" }, - "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true }, - "inputs": { "type": "object", "additionalProperties": true, "nullable": true }, - "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Node process data (JSON)." }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output content (JSON)." }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, - "error": { "type": "string", "nullable": true }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true }, - "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadata" , "nullable": true}, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "NodeExecutionMetadata": { - "type": "object", - "properties": { - "total_tokens": { "type": "integer", "nullable": true }, - "total_price": { "type": "number", "format": "float", "nullable": true, "description": "Using float for price compatibility, MD says decimal." }, - "currency": { "type": "string", "nullable": true, "example": "USD" } - } - }, - "StreamEventAdvWorkflowFinished": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "workflow_run_id", "data"], + "StreamEventChatMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Message end event, streaming has ended.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, + "metadata": { + "type": "object", + "description": "Metadata including usage and retriever resources.", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } } } ] }, - "WorkflowFinishedData": { - "type": "object", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], - "properties": { - "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output content (JSON)." }, - "error": { "type": "string", "nullable": true }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true }, - "total_tokens": { "type": "integer", "nullable": true }, - "total_steps": { "type": "integer", "default": 0 }, - "created_at": { "type": "integer", "format": "int64" }, - "finished_at": { "type": "integer", "format": "int64" } - } - }, - "StreamEventAdvError": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "status", "code", "message"], + "StreamEventChatMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Message content replacement event (e.g., due to content moderation).", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "May not always be present in a generic error." }, - "status": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" } + "answer": { + "type": "string", + "description": "Replacement content." + }, + "reason": { + "type": "string", + "description": "Reason for the content replacement." + } } } ] }, - "StreamEventAdvPing": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "type": "object" } ] + "StreamEventChatError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Error event during streaming.", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code." + }, + "code": { + "type": "string", + "description": "Error code." + }, + "message": { + "type": "string", + "description": "Error message." + } + } + } + ] + }, + "StreamEventChatPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "Ping event to keep connection alive." + } + ] }, "Usage": { - "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } + "type": "object", + "description": "Model usage information.", + "properties": { + "prompt_tokens": { + "type": "integer", + "description": "Number of tokens in the prompt." + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per prompt token." + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for prompt tokens." + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "Total price for prompt tokens." + }, + "completion_tokens": { + "type": "integer", + "description": "Number of tokens in the completion." + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per completion token." + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for completion tokens." + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "Total price for completion tokens." + }, + "total_tokens": { + "type": "integer", + "description": "Total number of tokens used." + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "Total price for all tokens." + }, + "currency": { + "type": "string", + "description": "Currency for pricing." + }, + "latency": { + "type": "number", + "format": "double", + "description": "Latency in seconds." + } + } }, "RetrieverResource": { - "type": "object", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } + "type": "object", + "description": "Citation and attribution information for a retriever resource.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of the retriever resource." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "ID of the message this resource belongs to." + }, + "position": { + "type": "integer", + "description": "Position of the resource in the list." + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "ID of the knowledge base." + }, + "dataset_name": { + "type": "string", + "description": "Name of the knowledge base." + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "ID of the document." + }, + "document_name": { + "type": "string", + "description": "Name of the document." + }, + "data_source_type": { + "type": "string", + "description": "Type of the data source." + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "ID of the specific chunk within the document." + }, + "score": { + "type": "number", + "format": "float", + "description": "Relevance score of the resource." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this chunk was hit." + }, + "word_count": { + "type": "integer", + "description": "Word count of the chunk." + }, + "segment_position": { + "type": "integer", + "description": "Position of the chunk within the document." + }, + "index_node_hash": { + "type": "string", + "description": "Hash of the index node." + }, + "content": { + "type": "string", + "description": "Content snippet from the resource." + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary of the chunk content." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." + } + } }, "FileUploadResponse": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "size": { "type": "integer" }, "extension": { "type": "string" }, "mime_type": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" } } + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique file ID." + }, + "name": { + "type": "string", + "description": "File name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "nullable": true, + "description": "File extension." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Upload timestamp (Unix epoch seconds)." + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "Preview URL for the file." + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "Source URL of the file." + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "Original URL of the file." + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated user." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated tenant." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated conversation." + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "Storage key for the file." + } + } }, "EndUserDetail": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "Tenant ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Application ID." + }, + "type": { + "type": "string", + "description": "End user type. Always `service_api` for Service API users." + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/api-reference/chats/send-chat-message))." + }, + "name": { + "type": "string", + "nullable": true, + "description": "End user name." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request." + }, + "session_id": { + "type": "string", + "description": "Session identifier. Defaults to the `external_user_id` value." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } } }, "MessageFeedbackRequest": { - "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "user": { "type": "string" }, "content": { "type": "string", "nullable": true } } + "type": "object", + "description": "Request body for submitting message feedback.", + "required": [ + "user" + ], + "properties": { + "rating": { + "type": "string", + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "Feedback rating. Set to `null` to revoke previously submitted feedback." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer, must ensure uniqueness within the application." + }, + "content": { + "type": "string", + "description": "Optional text feedback providing additional detail." + } + } }, "AppFeedbacksResponse": { - "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItem" } } } + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "List of feedback items.", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } + } + } }, "FeedbackItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } + "type": "object", + "description": "A single feedback item.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Feedback ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "Application ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + }, + "content": { + "type": "string", + "nullable": true, + "description": "Optional text feedback." + }, + "from_source": { + "type": "string", + "description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console." + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "End user ID who submitted the feedback. Present when `from_source` is `user`." + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Account ID who submitted the feedback. Present when `from_source` is `admin`." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } + } }, "SuggestedQuestionsResponse": { - "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" } } } + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Result status." + }, + "data": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of suggested questions." + } + } }, "ConversationHistoryResponse": { - "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessageItem" } } } + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more messages." + }, + "data": { + "type": "array", + "description": "List of messages.", + "items": { + "$ref": "#/components/schemas/ConversationMessageItem" + } + } + } }, "ConversationMessageItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "inputs": { "type": "object", "additionalProperties": true }, "query": { "type": "string" }, "answer": { "type": "string" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItem" } }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"] } } }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResource" } }, "created_at": { "type": "integer", "format": "int64" } } + "type": "object", + "description": "A single message in a conversation.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "parent_message_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Parent message ID for threaded conversations." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for this message." + }, + "query": { + "type": "string", + "description": "User query text." + }, + "answer": { + "type": "string", + "description": "Assistant answer text." + }, + "status": { + "type": "string", + "description": "Message status. `normal` for successful messages, `error` when generation failed." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if `status` is `error`." + }, + "message_files": { + "type": "array", + "description": "Files attached to this message.", + "items": { + "$ref": "#/components/schemas/MessageFileItem" + } + }, + "feedback": { + "type": "object", + "nullable": true, + "description": "User feedback for this message.", + "properties": { + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + } + } + }, + "retriever_resources": { + "type": "array", + "description": "Retriever resources used for this message.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + }, + "agent_thoughts": { + "type": "array", + "description": "Agent thoughts for this message.", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." + }, + "extra_contents": { + "type": "array", + "description": "Additional execution content associated with this message, such as human input form data from Human Input nodes in chatflow workflows.", + "items": { + "$ref": "#/components/schemas/HumanInputContent" + } + } + } }, "MessageFileItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "url": { "type": "string", "format": "url" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"] } } + "type": "object", + "description": "A file attached to a message.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "Original filename." + }, + "type": { + "type": "string", + "description": "File type, e.g., `image`." + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "Preview URL for the file." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "size": { + "type": "integer", + "nullable": true, + "description": "File size in bytes." + }, + "transfer_method": { + "type": "string", + "description": "Transfer method used. `remote_url` for URL-based files, `local_file` for uploaded files, `tool_file` for tool-generated files." + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "Who this file belongs to. `user` for user-uploaded files, `assistant` for assistant-generated files." + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Upload file ID if transferred via `local_file`." + } + } + }, + "AgentThoughtItem": { + "type": "object", + "description": "An agent thought step in the message.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Agent thought ID." + }, + "chain_id": { + "type": "string", + "nullable": true, + "description": "Chain ID for this thought." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID this thought belongs to." + }, + "position": { + "type": "integer", + "description": "Position of this thought." + }, + "thought": { + "type": "string", + "description": "What LLM is thinking." + }, + "tool": { + "type": "string", + "description": "Tools called, split by `;`." + }, + "tool_labels": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Labels for tools used." + }, + "tool_input": { + "type": "string", + "description": "Input of tools in JSON format." + }, + "observation": { + "type": "string", + "description": "Response from tool calls." + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "File IDs related to this thought." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + } + } }, "ConversationsListResponse": { - "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItem" } } } + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more conversations." + }, + "data": { + "type": "array", + "description": "List of conversations.", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } + } + } }, "ConversationListItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": true }, "status": { "type": "string" }, "introduction": { "type": "string", "nullable": true }, "created_at": { "type": "integer", "format": "int64" }, "updated_at": { "type": "integer", "format": "int64" } } + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "name": { + "type": "string", + "description": "Conversation name." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the conversation." + }, + "status": { + "type": "string", + "description": "Conversation status. `normal` for active conversations." + }, + "introduction": { + "type": "string", + "description": "Conversation introduction." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update timestamp." + } + } }, "ConversationRenameRequest": { - "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true }, "auto_generate": { "type": "boolean", "default": false }, "user": { "type": "string" } } + "type": "object", + "description": "Request body for renaming a conversation.", + "required": [ + "user" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the conversation. Required when `auto_generate` is `false`." + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "Automatically generate the conversation name. When `true`, the `name` field is ignored." + }, + "user": { + "type": "string", + "description": "The user identifier." + } + } }, - "ConversationRenameResponse": { "$ref": "#/components/schemas/ConversationListItem" }, "ConversationVariablesResponse": { - "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItem" } } } + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there is a next page." + }, + "data": { + "type": "array", + "description": "List of conversation variables.", + "items": { + "$ref": "#/components/schemas/ConversationVariableItem" + } + } + } }, "ConversationVariableItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "value_type": { "type": "string" }, "value": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "integer", "format": "int64" }, "updated_at": { "type": "integer", "format": "int64" } } + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Variable ID." + }, + "name": { + "type": "string", + "description": "Variable name." + }, + "value_type": { + "type": "string", + "description": "Variable value type. Possible values: `string`, `number`, `object`, `secret`, `file`, `boolean`, `array[any]`, `array[string]`, `array[number]`, `array[object]`, `array[file]`, `array[boolean]`." + }, + "value": { + "type": "string", + "description": "Variable value (can be a JSON string for complex types)." + }, + "description": { + "type": "string", + "description": "Variable description." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update timestamp." + } + } + }, + "ConversationVariableUpdateRequest": { + "type": "object", + "description": "Request body for updating a conversation variable.", + "required": [ + "value" + ], + "properties": { + "value": { + "description": "The new value for the variable. Must match the variable's expected type." + }, + "user": { + "type": "string", + "description": "User identifier." + } + } }, "AudioToTextRequest": { - "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file. Formats: mp3, mp4, mpeg, mpga, m4a, wav, webm. Limit: 15MB." }, "user": { "type": "string" } } - }, - "AudioToTextResponse": { "type": "object", "properties": { "text": { "type": "string" } } }, - "TextToAudioJsonRequest": { - "type": "object", "required": ["user"], + "type": "object", + "description": "Request body for audio-to-text conversion.", + "required": [ + "file" + ], "properties": { - "message_id": { "type": "string", "format": "uuid", "description": "Message ID (priority)." }, - "text": { "type": "string", "description": "Speech content." }, - "user": { "type": "string" }, - "streaming": {"type": "boolean", "default": false, "description": "If true, response will be a stream of audio chunks."} - }, - "description": "Requires `user`. Provide `message_id` or `text`." + "file": { + "type": "string", + "format": "binary", + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `30 MB`." + }, + "user": { + "type": "string", + "description": "User identifier." + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "Output text from speech recognition." + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID. Takes priority over `text` when both are provided." + }, + "text": { + "type": "string", + "description": "Speech content to convert." + }, + "user": { + "type": "string", + "description": "User identifier." + }, + "voice": { + "type": "string", + "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." + }, + "streaming": { + "type": "boolean", + "description": "Whether to enable streaming response." + } + } }, "AppInfoResponse": { - "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Application name." + }, + "description": { + "type": "string", + "description": "Application description." + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Application tags." + }, + "mode": { + "type": "string", + "description": "Application mode. `completion` for text generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for chatflow apps, `workflow` for workflow apps." + }, + "author_name": { + "type": "string", + "description": "Name of the application author." + } + } }, "ChatAppParametersResponse": { - "type": "object", "properties": { "opening_statement": { "type": "string" }, "suggested_questions": { "type": "array", "items": { "type": "string" } }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "voice": { "type": "string" }, "language": { "type": "string" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"] } } }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItem" } }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } } } } }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer" }, "image_file_size_limit": { "type": "integer" }, "audio_file_size_limit": { "type": "integer" }, "video_file_size_limit": { "type": "integer" } } } } + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "Opening statement displayed at conversation start." + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of suggested starter questions." + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "Configuration for suggested questions after answer.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "speech_to_text": { + "type": "object", + "description": "Speech-to-text configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "text_to_speech": { + "type": "object", + "description": "Text-to-speech configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + }, + "voice": { + "type": "string", + "description": "Voice identifier for TTS." + }, + "language": { + "type": "string", + "description": "Language for TTS." + }, + "autoPlay": { + "type": "string", + "description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play." + } + } + }, + "retriever_resource": { + "type": "object", + "description": "Retriever resource configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "annotation_reply": { + "type": "object", + "description": "Annotation reply configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "more_like_this": { + "type": "object", + "description": "More-like-this configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "Sensitive word avoidance configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "user_input_form": { + "type": "array", + "description": "List of user input form elements.", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "File upload configuration.", + "properties": { + "image": { + "type": "object", + "description": "Image upload settings.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether image upload is enabled." + }, + "number_limits": { + "type": "integer", + "description": "Maximum number of images." + }, + "detail": { + "type": "string", + "description": "Image detail level." + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Allowed transfer methods." + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "System-level parameters and limits.", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "Maximum file size in MB." + }, + "image_file_size_limit": { + "type": "integer", + "description": "Maximum image file size in MB." + }, + "audio_file_size_limit": { + "type": "integer", + "description": "Maximum audio file size in MB." + }, + "video_file_size_limit": { + "type": "integer", + "description": "Maximum video file size in MB." + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "Maximum number of files for workflow file upload." + } + } + } + } }, - "UserInputFormItem": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapper" }, { "$ref": "#/components/schemas/ParagraphControlWrapper" }, { "$ref": "#/components/schemas/SelectControlWrapper" } ] }, - "TextInputControlWrapper": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } }, "required":["text-input"] }, - "ParagraphControlWrapper": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } }, "required":["paragraph"] }, - "SelectControlWrapper": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } }, "required":["select"] }, - "TextInputControl": { "type": "object", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } }, - "ParagraphControl": { "type": "object", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } }, - "SelectControl": { "type": "object", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } } }, - "AppMetaResponse": { "type": "object", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url" }, { "$ref": "#/components/schemas/ToolIconDetail" } ] } } } }, - "ToolIconDetail": { "type": "object", "properties": { "background": { "type": "string" }, "content": { "type": "string" } } }, - "WebAppSettingsResponse": { "type": "object", "properties": { "title": { "type": "string" }, "chat_color_theme": { "type": "string" }, "chat_color_theme_inverted": { "type": "boolean" }, "icon_type": { "type": "string", "enum": ["emoji", "image"] }, "icon": { "type": "string" }, "icon_background": { "type": "string" }, "icon_url": { "type": "string", "format": "url", "nullable": true }, "description": { "type": "string" }, "copyright": { "type": "string" }, "privacy_policy": { "type": "string" }, "custom_disclaimer": { "type": "string" }, "default_language": { "type": "string" }, "show_workflow_steps": { "type": "boolean" }, "use_icon_as_answer_icon": { "type": "boolean" } } }, - "AnnotationListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItem" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } }, - "AnnotationItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "question": { "type": "string" }, "answer": { "type": "string" }, "hit_count": { "type": "integer" }, "created_at": { "type": "integer", "format": "int64" } } }, - "CreateAnnotationRequest": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } }, - "UpdateAnnotationRequest": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } }, - "InitialAnnotationReplySettingsRequest": { "type": "object", "required": ["score_threshold"], "properties": { "embedding_provider_name": { "type": "string", "nullable": true }, "embedding_model_name": { "type": "string", "nullable": true }, "score_threshold": { "type": "number", "format": "float" } } }, - "InitialAnnotationReplySettingsResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "job_status": { "type": "string" } } }, - "InitialAnnotationReplySettingsStatusResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "job_status": { "type": "string" }, "error_msg": { "type": "string", "nullable": true } } }, - "ErrorResponse": { "type": "object", "properties": { "status": { "type": "integer", "nullable": true }, "code": { "type": "string", "nullable": true }, "message": { "type": "string" } } } + "UserInputFormItem": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } + ] + }, + "TextInputControlWrapper": { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } + }, + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } + }, + "SelectControlWrapper": { + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } + }, + "TextInputControl": { + "type": "object", + "description": "Text input form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether input is required." + }, + "default": { + "type": "string", + "description": "Default value." + } + } + }, + "ParagraphControl": { + "type": "object", + "description": "Paragraph (multi-line text) form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether input is required." + }, + "default": { + "type": "string", + "description": "Default value." + } + } + }, + "SelectControl": { + "type": "object", + "description": "Select (dropdown) form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether selection is required." + }, + "default": { + "type": "string", + "description": "Default selected value." + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of selectable values for this form control." + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "URL of the icon." + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "Tool icons. Keys are tool names." + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "Detail of a tool icon using emoji.", + "properties": { + "background": { + "type": "string", + "description": "Background color in hex format." + }, + "content": { + "type": "string", + "description": "Emoji content." + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp title." + }, + "chat_color_theme": { + "type": "string", + "description": "Chat color theme." + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "Whether the chat color theme is inverted." + }, + "icon_type": { + "type": "string", + "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." + }, + "icon": { + "type": "string", + "description": "Icon content (emoji or image ID)." + }, + "icon_background": { + "type": "string", + "description": "Icon background color." + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "URL of the icon image." + }, + "description": { + "type": "string", + "description": "WebApp description." + }, + "copyright": { + "type": "string", + "description": "Copyright text." + }, + "privacy_policy": { + "type": "string", + "description": "Privacy policy URL." + }, + "custom_disclaimer": { + "type": "string", + "description": "Custom disclaimer text." + }, + "default_language": { + "type": "string", + "description": "Default language code." + }, + "show_workflow_steps": { + "type": "boolean", + "description": "Whether to show workflow steps." + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "Whether to use the app icon as the answer icon." + } + } + }, + "AnnotationListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "description": "List of annotation items for the current page." + }, + "has_more": { + "type": "boolean", + "description": "`true` if more pages are available beyond the current result set." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of annotations matching the query." + }, + "page": { + "type": "integer", + "description": "Current page number." + } + } + }, + "AnnotationItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique annotation identifier." + }, + "question": { + "type": "string", + "nullable": true, + "description": "Question text that triggers this annotation." + }, + "answer": { + "type": "string", + "nullable": true, + "description": "Predefined answer returned when the annotation is matched." + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "Number of times this annotation has been matched and returned as a reply." + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Creation timestamp (Unix epoch seconds)." + } + } + }, + "CreateAnnotationRequest": { + "type": "object", + "description": "Request body for creating a new annotation.", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "Annotation question." + }, + "answer": { + "type": "string", + "description": "Annotation answer." + } + } + }, + "UpdateAnnotationRequest": { + "type": "object", + "description": "Request body for updating an annotation.", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "Updated annotation question." + }, + "answer": { + "type": "string", + "description": "Updated annotation answer." + } + } + }, + "InitialAnnotationReplySettingsRequest": { + "type": "object", + "description": "Request body for configuring annotation reply settings.", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], + "properties": { + "embedding_provider_name": { + "type": "string", + "description": "Name of the embedding model provider (e.g., `openai`, `cohere`)." + }, + "embedding_model_name": { + "type": "string", + "description": "Name of the embedding model to use for annotation matching (e.g., `text-embedding-3-small`)." + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "Minimum similarity score for an annotation to be considered a match. Higher values require closer matches.", + "minimum": 0, + "maximum": 1 + } + } + }, + "InitialAnnotationReplySettingsResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "Asynchronous job ID. Use with [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress." + }, + "job_status": { + "type": "string", + "description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed." + } + } + }, + "InitialAnnotationReplySettingsStatusResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "Job ID from the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call." + }, + "job_status": { + "type": "string", + "description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed." + }, + "error_msg": { + "type": "string", + "description": "Error message describing why the job failed. Empty string when `job_status` is not `error`." + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Workflow execution started.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "description": "Associated workflow ID." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for this workflow execution." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "reason": { + "type": "string", + "description": "Reason for workflow start. `initial` for first start, `resumption` when resuming after a pause (e.g., after human input)." + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Workflow execution finished.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "description": "Associated workflow ID." + }, + "status": { + "type": "string", + "description": "Execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `stopped` if manually stopped, `partial-succeeded` if partially completed, `paused` when waiting for human input." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Workflow output data." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if execution failed." + }, + "elapsed_time": { + "type": "number", + "description": "Total execution time in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total steps executed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Finish timestamp (Unix epoch seconds)." + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "Number of exceptions during execution." + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files generated during workflow execution." + } + } + } + } + } + ] + }, + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Node execution started.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type (e.g., `llm`, `knowledge-retrieval`, `code`)." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "Execution index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node." + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node input data. May be `null` in simplified API responses." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Iteration ID if this node runs inside an iteration." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Loop ID if this node runs inside a loop." + } + } + } + } + } + ] + }, + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Node execution finished.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "Execution index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node." + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node input data. May be `null` in simplified API responses." + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node processing data. May be `null` in simplified API responses." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node output data. May be `null` in simplified API responses." + }, + "status": { + "type": "string", + "description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if node failed." + }, + "elapsed_time": { + "type": "number", + "description": "Node execution time in seconds." + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Execution metadata (e.g., token usage, model info). May be `null` in simplified API responses." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Finish timestamp (Unix epoch seconds)." + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files generated by this node." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Iteration ID if this node runs inside an iteration." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Loop ID if this node runs inside a loop." + } + } + } + } + } + ] + }, + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Node retry attempt.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "Execution index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node." + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node input data." + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node processing data." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node output data." + }, + "status": { + "type": "string", + "description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message for this retry attempt." + }, + "elapsed_time": { + "type": "number", + "description": "Execution time for this attempt in seconds." + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Execution metadata." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Finish timestamp (Unix epoch seconds)." + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files generated during this retry." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Iteration ID if applicable." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Loop ID if applicable." + }, + "retry_index": { + "type": "integer", + "description": "Retry attempt index, starts at `0`." + } + } + } + } + } + ] + }, + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Iteration loop started.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Iteration execution ID." + }, + "node_id": { + "type": "string", + "description": "Iteration node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Iteration node title." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Iteration metadata." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Iteration input data." + } + } + } + } + } + ] + }, + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Iteration progressed to next item.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Iteration execution ID." + }, + "node_id": { + "type": "string", + "description": "Iteration node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Iteration node title." + }, + "index": { + "type": "integer", + "description": "Current iteration index (0-based)." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Timestamp (Unix epoch seconds)." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Iteration loop completed.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Iteration execution ID." + }, + "node_id": { + "type": "string", + "description": "Iteration node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Iteration node title." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Iteration output data." + }, + "status": { + "type": "string", + "description": "Iteration execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if iteration failed." + }, + "elapsed_time": { + "type": "number", + "description": "Total iteration time in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed across all iterations." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Finish timestamp (Unix epoch seconds)." + }, + "steps": { + "type": "integer", + "description": "Total number of iteration steps executed." + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Loop started.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Loop execution ID." + }, + "node_id": { + "type": "string", + "description": "Loop node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Loop node title." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Loop metadata." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Loop input data." + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Loop progressed to next iteration.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Loop execution ID." + }, + "node_id": { + "type": "string", + "description": "Loop node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Loop node title." + }, + "index": { + "type": "integer", + "description": "Current loop index (0-based)." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Timestamp (Unix epoch seconds)." + }, + "pre_loop_output": { + "description": "Output from the previous loop iteration." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Loop completed.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Loop execution ID." + }, + "node_id": { + "type": "string", + "description": "Loop node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Loop node title." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Loop output data." + }, + "status": { + "type": "string", + "description": "Loop execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if loop failed." + }, + "elapsed_time": { + "type": "number", + "description": "Total loop execution time in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed across all loop iterations." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Finish timestamp (Unix epoch seconds)." + }, + "steps": { + "type": "integer", + "description": "Total number of loop steps executed." + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Human input node is waiting for user input.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "Form ID for submitting the response." + }, + "node_id": { + "type": "string", + "description": "Node ID of the human input node." + }, + "node_title": { + "type": "string", + "description": "Title of the human input node." + }, + "form_content": { + "type": "string", + "description": "Form content/instructions for the user." + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Form input field definitions." + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Available user actions." + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "Token for form submission authentication." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp when the form expires." + } + } + } + } + } + ] + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of paused node IDs." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "Partial outputs at pause time." + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Reasons for pausing." + }, + "status": { + "type": "string", + "description": "Workflow execution status." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total elapsed time in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total steps executed." + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "Rendered content after form submission." + }, + "action_id": { + "type": "string", + "description": "ID of the action taken." + }, + "action_text": { + "type": "string", + "description": "Text of the action taken." + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp when the form expired." + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Agent log from an agent node within the workflow.", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "Node execution ID." + }, + "id": { + "type": "string", + "description": "Log entry ID." + }, + "label": { + "type": "string", + "description": "Log entry label." + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "Parent log entry ID for nested entries." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if applicable." + }, + "status": { + "type": "string", + "description": "Log entry status." + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "Log entry data." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + } + } + } + } + } + ] + }, + "StreamEventChatTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The text content chunk." + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "Source path of the text variable in the workflow." + } + } + } + } + } + ] + }, + "StreamEventChatTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The replacement text content." + } + } + } + } + } + ] + }, + "WorkflowRunDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the workflow run." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Output data from the workflow." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "Total time elapsed in seconds." + } + } + }, + "WorkflowLogsResponse": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "description": "Current page number." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of log entries." + }, + "has_more": { + "type": "boolean", + "description": "Whether more pages are available." + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "List of workflow log entries." + } + } + }, + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Log entry ID." + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "Source of the workflow run (e.g., `service-api`)." + }, + "created_by_role": { + "type": "string", + "description": "Role of the creator (e.g., `end_user`, `account`)." + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "Account details if created by an admin user.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Account ID." + }, + "name": { + "type": "string", + "description": "Account display name." + }, + "email": { + "type": "string", + "description": "Account email address." + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the log entry was created." + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Additional details for the log entry." + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "version": { + "type": "string", + "description": "Workflow version identifier." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total time elapsed in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "exceptions_count": { + "type": "integer", + "description": "Number of exceptions that occurred during execution." + }, + "triggered_from": { + "type": "string", + "description": "Source that triggered the workflow run. `debugging` for test runs from the editor, `app` for API or app-initiated runs." + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "type": { + "type": "string", + "description": "End user type." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the end user is anonymous." + }, + "session_id": { + "type": "string", + "description": "Session identifier." + } + } + }, + "HumanInputContent": { + "type": "object", + "description": "Execution content from a Human Input node, including form definition and submission data.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ID of the workflow run this content belongs to." + }, + "submitted": { + "type": "boolean", + "description": "Whether the human input form has been submitted." + }, + "type": { + "type": "string", + "description": "`human_input` for human input content." + }, + "form_definition": { + "nullable": true, + "description": "Form definition from the Human Input node. `null` when the content represents a submission response.", + "$ref": "#/components/schemas/HumanInputFormDefinition" + }, + "form_submission_data": { + "nullable": true, + "description": "Submitted form data. `null` when the form has not been submitted yet.", + "$ref": "#/components/schemas/HumanInputFormSubmissionData" + } + } + }, + "HumanInputFormDefinition": { + "type": "object", + "description": "Definition of a human input form rendered by a Human Input node.", + "properties": { + "form_id": { + "type": "string", + "description": "Unique form identifier." + }, + "node_id": { + "type": "string", + "description": "ID of the Human Input node that generated this form." + }, + "node_title": { + "type": "string", + "description": "Title of the Human Input node." + }, + "form_content": { + "type": "string", + "description": "Markdown or text content displayed with the form." + }, + "inputs": { + "type": "array", + "description": "Input fields in the form.", + "items": { + "$ref": "#/components/schemas/FormInput" + } + }, + "actions": { + "type": "array", + "description": "Action buttons available on the form.", + "items": { + "$ref": "#/components/schemas/UserAction" + } + }, + "display_in_ui": { + "type": "boolean", + "description": "Whether the form should be displayed in the UI." + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "Token for form submission authentication." + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "Resolved default values for form inputs, keyed by output variable name." + }, + "expiration_time": { + "type": "integer", + "description": "Unix timestamp when the form expires." + } + } + }, + "HumanInputFormSubmissionData": { + "type": "object", + "description": "Data from a submitted human input form.", + "properties": { + "node_id": { + "type": "string", + "description": "ID of the Human Input node." + }, + "node_title": { + "type": "string", + "description": "Title of the Human Input node." + }, + "rendered_content": { + "type": "string", + "description": "Rendered content of the form submission." + }, + "action_id": { + "type": "string", + "description": "ID of the action button that was clicked." + }, + "action_text": { + "type": "string", + "description": "Display text of the action button that was clicked." + } + } + }, + "FormInput": { + "type": "object", + "description": "A form input field definition.", + "properties": { + "type": { + "type": "string", + "description": "`text_input` for single-line text, `paragraph` for multi-line text." + }, + "output_variable_name": { + "type": "string", + "description": "Variable name where the input value is stored." + }, + "default": { + "nullable": true, + "description": "Default value configuration for this input.", + "$ref": "#/components/schemas/FormInputDefault" + } + } + }, + "FormInputDefault": { + "type": "object", + "description": "Default value configuration for a form input.", + "properties": { + "type": { + "type": "string", + "description": "`variable` for dynamic values from workflow variables, `constant` for static values." + }, + "selector": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Variable selector path when `type` is `variable`." + }, + "value": { + "type": "string", + "description": "Static value when `type` is `constant`." + } + } + }, + "UserAction": { + "type": "object", + "description": "An action button on a human input form.", + "properties": { + "id": { + "type": "string", + "description": "Unique action identifier." + }, + "title": { + "type": "string", + "description": "Button display text." + }, + "button_style": { + "type": "string", + "description": "`primary`, `default`, `accent`, or `ghost`." + } + } + } } }, "tags": [ - { "name": "Chatflow", "description": "Advanced chat operations with workflow events." }, - { "name": "Files", "description": "File upload and preview operations for advanced chat." }, - { "name": "End Users", "description": "Operations related to end user information." }, - { "name": "Feedback", "description": "User feedback operations for advanced chat." }, - { "name": "Conversations", "description": "Conversation management for advanced chat." }, - { "name": "TTS", "description": "Speech and Text conversion for advanced chat." }, - { "name": "Application", "description": "Application settings and info for advanced chat." }, - { "name": "Annotations", "description": "Annotation management for advanced chat." } + { + "name": "Chats", + "description": "Operations related to chat messages and interactions." + }, + { + "name": "Files", + "description": "File upload and preview operations." + }, + { + "name": "End Users", + "description": "Operations related to end user information." + }, + { + "name": "Feedback", + "description": "User feedback operations." + }, + { + "name": "Conversations", + "description": "Operations related to managing conversations." + }, + { + "name": "TTS", + "description": "Text-to-Speech and Speech-to-Text operations." + }, + { + "name": "Applications", + "description": "Operations to retrieve application settings and information." + }, + { + "name": "Annotations", + "description": "Operations related to managing annotations for direct replies." + }, + { + "name": "Workflow Runs", + "description": "Operations related to workflow execution details and logs." + } ] } diff --git a/en/api-reference/openapi_completion.json b/en/api-reference/openapi_completion.json index 3fcda724..801795a8 100644 --- a/en/api-reference/openapi_completion.json +++ b/en/api-reference/openapi_completion.json @@ -8,7 +8,7 @@ "servers": [ { "url": "{api_base_url}", - "description": "The base URL for the Completion App API. Replace {api_base_url} with the actual API base URL provided for your application (e.g., from props.appDetail.api_base_url).", + "description": "The base URL for the Completion App API. Replace {api_base_url} with the actual API base URL provided for your application.", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", @@ -25,10 +25,12 @@ "paths": { "/completion-messages": { "post": { - "summary": "Create Completion Message", + "summary": "Send Completion Message", "description": "Send a request to the text generation application.", "operationId": "createCompletionMessage", - "tags": ["Completion"], + "tags": [ + "Completions" + ], "requestBody": { "description": "Request body to create a completion message.", "required": true, @@ -39,17 +41,30 @@ }, "examples": { "streaming_example": { - "summary": "Streaming mode example", + "summary": "Request Example - Streaming mode", "value": { - "inputs": {"query": "Hello, world!"}, + "inputs": { + "city": "San Francisco" + }, + "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", - "user": "abc-123" + "user": "abc-123", + "files": [ + { + "type": "image", + "transfer_method": "remote_url", + "url": "https://cloud.dify.ai/logo/logo-site.png" + } + ] } }, "blocking_example": { - "summary": "Blocking mode example", + "summary": "Request Example - Blocking mode", "value": { - "inputs": {"query": "Translate this to French: Hello"}, + "inputs": { + "city": "New York" + }, + "query": "Summarize the following text: ...", "response_mode": "blocking", "user": "def-456" } @@ -60,7 +75,7 @@ }, "responses": { "200": { - "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n- If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a `ChunkCompletionResponse` stream.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkCompletionEvent` objects.", "content": { "application/json": { "schema": { @@ -68,9 +83,11 @@ }, "examples": { "blockingResponse": { - "summary": "Example of a blocking mode response", + "summary": "Response Example - Blocking mode", "value": { "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "mode": "completion", "answer": "Hello World!...", @@ -98,177 +115,97 @@ "text/event-stream": { "schema": { "type": "string", - "description": "A stream of Server-Sent Events. Each event is a JSON object prefixed with 'data: ' and suffixed with '\\n\\n'. See `ChunkCompletionEvent` for possible event structures." + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkCompletionEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `message_end` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." }, "examples": { "streamingResponse": { - "summary": "Example of a streaming mode response", - "value": "data: {\"event\": \"message\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\ndata: {\"event\": \"tts_message\", \"task_id\": \"3bf8a0bb-e73b-4690-9e66-4e429bad8ee7\", \"message_id\": \"a8bdc41c-13b2-4c18-bfd9-054b9803038c\", \"created_at\": 1721205487, \"audio\": \"base64encodedaudio...\"}\n\ndata: {\"event\": \"tts_message_end\", \"task_id\": \"3bf8a0bb-e73b-4690-9e66-4e429bad8ee7\", \"message_id\": \"a8bdc41c-13b2-4c18-bfd9-054b9803038c\", \"created_at\": 1721205487, \"audio\": \"\"}\n\n" + "summary": "Response Example - Streaming mode", + "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n" } } } } }, "400": { - "description": "Bad Request. Possible error codes:\n- `invalid_param`: Abnormal parameter input.\n- `app_unavailable`: App configuration unavailable.\n- `provider_not_initialize`: No available model credential configuration.\n- `provider_quota_exceeded`: Model invocation quota insufficient.\n- `model_currently_not_support`: Current model unavailable.\n- `completion_request_error`: Text generation failed.", + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "404": { - "description": "Conversation does not exist.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "500": { - "description": "Internal server error.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - } - } - } - }, - "/files/upload": { - "post": { - "summary": "File Upload", - "description": "Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text. Supports png, jpg, jpeg, webp, gif formats. Uploaded files are for use by the current end-user only.", - "operationId": "uploadFile", - "tags": ["Files"], - "requestBody": { - "description": "File upload request. Requires multipart/form-data.", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "The file to be uploaded. Supported image types: png, jpg, jpeg, webp, gif." - }, - "user": { - "type": "string", - "description": "User identifier, defined by the developer's rules, must be unique within the application." - } - } - } - } - } - }, - "responses": { - "200": { - "description": "File uploaded successfully.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponse" - }, "examples": { - "success": { + "app_unavailable": { + "summary": "app_unavailable", "value": { - "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67", - "name": "example.png", - "size": 1024, - "extension": "png", - "mime_type": "image/png", - "created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13", - "created_at": 1577836800 + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." } } } } } }, - "400": { - "description": "Bad Request. Possible error codes:\n- `no_file_uploaded`: A file must be provided.\n- `too_many_files`: Currently only one file is accepted.\n- `unsupported_preview`: The file does not support preview.\n- `unsupported_estimate`: The file does not support estimation.", + "429": { + "description": "`too_many_requests` : Too many concurrent requests for this app.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "413": { - "description": "`file_too_large`: The file is too large.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "415": { - "description": "`unsupported_file_type`: Unsupported extension. Currently only document files are accepted (Note: description says image types png, jpg, etc. are supported for this endpoint, but this error message refers to document files. Clarification might be needed from source documentation).", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "503": { - "description": "Service Unavailable. Possible error codes:\n- `s3_connection_failed`: Unable to connect to S3 service.\n- `s3_permission_denied`: No permission to upload files to S3.\n- `s3_file_too_large`: File exceeds S3 size limit.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + } + } } } }, "500": { - "description": "Internal server error.", + "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "Get End User", - "description": "Retrieve an end user by ID.\n\nThis is useful when other APIs return an end-user ID (e.g. `created_by` from File Upload).", - "operationId": "getEndUserCompletion", - "tags": ["End Users"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "End user ID.", - "schema": { "type": "string", "format": "uuid" } - } - ], - "responses": { - "200": { - "description": "End user retrieved successfully.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetail" } - } - } - }, - "404": { - "description": "End user not found. Error code: `end_user_not_found`", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "500": { - "description": "Internal server error.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -277,16 +214,18 @@ }, "/completion-messages/{task_id}/stop": { "post": { - "summary": "Stop Generate", - "description": "Stops a generation task. Only supported in streaming mode.", + "summary": "Stop Completion Message Generation", + "description": "Stops a completion message generation task. Only supported in `streaming` mode.", "operationId": "stopGenerate", - "tags": ["Completion"], + "tags": [ + "Completions" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "Task ID, can be obtained from the streaming chunk return of a `/completion-messages` request.", + "description": "Task ID, can be obtained from the streaming chunk return of the [Send Completion Message](/api-reference/completions/send-completion-message) API.", "schema": { "type": "string" } @@ -298,16 +237,19 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { "user": { "type": "string", - "description": "User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface." + "description": "User identifier, must be consistent with the user passed in the send message interface." } } }, "examples": { - "example":{ + "example": { + "summary": "Request Example", "value": { "user": "abc-123" } @@ -318,22 +260,19 @@ }, "responses": { "200": { - "description": "Stop request successful.", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`app_unavailable` : App unavailable or misconfigured.", "content": { "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" - } - } - }, "examples": { - "success": { + "app_unavailable": { + "summary": "app_unavailable", "value": { - "result": "success" + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." } } } @@ -345,16 +284,18 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "summary": "Message Feedback", - "description": "End-users can provide feedback messages, facilitating application developers to optimize expected outputs.", "operationId": "postMessageFeedback", - "tags": ["Feedback"], + "tags": [ + "Feedback" + ], + "summary": "Submit Message Feedback", + "description": "Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.", "parameters": [ { "name": "message_id", "in": "path", "required": true, - "description": "Message ID for which feedback is being provided.", + "description": "Message ID.", "schema": { "type": "string" } @@ -368,11 +309,12 @@ "$ref": "#/components/schemas/MessageFeedbackRequest" }, "examples": { - "like_example": { + "likeFeedback": { + "summary": "Request Example", "value": { "rating": "like", "user": "abc-123", - "content": "message feedback information" + "content": "This answer was very helpful!" } } } @@ -381,22 +323,19 @@ }, "responses": { "200": { - "description": "Feedback submitted successfully.", + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : Message does not exist.", "content": { "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" - } - } - }, "examples": { - "success": { + "message_not_exists": { + "summary": "not_found", "value": { - "result": "success" + "status": 404, + "code": "not_found", + "message": "Message Not Exists." } } } @@ -408,29 +347,34 @@ }, "/app/feedbacks": { "get": { - "summary": "Get feedbacks of application", - "description": "Get application's feedbacks.", "operationId": "getAppFeedbacks", - "tags": ["Feedback"], + "tags": [ + "Feedback" + ], + "summary": "List App Feedbacks", + "description": "Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.", "parameters": [ { "name": "page", "in": "query", - "description": "(optional) Pagination page number. Default: 1", + "description": "Page number for pagination.", "required": false, "schema": { - "type": "integer", - "default": 1 + "type": "integer", + "default": 1, + "minimum": 1 } }, { "name": "limit", "in": "query", - "description": "(optional) Records per page. Default: 20", + "description": "Number of records per page.", "required": false, "schema": { "type": "integer", - "default": 20 + "default": 20, + "minimum": 1, + "maximum": 101 } } ], @@ -443,21 +387,35 @@ "$ref": "#/components/schemas/AppFeedbacksResponse" }, "examples": { - "success": { + "feedbacksList": { + "summary": "Response Example", "value": { "data": [ { - "id": "8c0fbed8-e2f9-49ff-9f0e-15a35bdd0e25", - "app_id": "f252d396-fe48-450e-94ec-e184218e7346", - "conversation_id": "2397604b-9deb-430e-b285-4726e51fd62d", - "message_id": "709c0b0f-0a96-4a4e-91a4-ec0889937b11", + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "rating": "like", - "content": "message feedback information-3", + "content": "The response accurately answered my question about product specifications.", "from_source": "user", - "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "from_account_id": null, - "created_at": "2025-04-24T09:24:38", - "updated_at": "2025-04-24T09:24:38" + "created_at": "2025-01-16T14:30:29Z", + "updated_at": "2025-01-16T14:30:29Z" + }, + { + "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", + "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", + "rating": "dislike", + "content": "The answer was too vague and did not address the specific pricing question.", + "from_source": "user", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", + "from_account_id": null, + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" } ] } @@ -469,12 +427,461 @@ } } }, + "/files/upload": { + "post": { + "operationId": "uploadFile", + "tags": [ + "Files" + ], + "summary": "Upload File", + "description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", + "requestBody": { + "description": "File upload request. Requires multipart/form-data.", + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "The file to be uploaded. Supported types include images, documents, audio, and video." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer's rules, must be unique within the application." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "File uploaded successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : File size exceeded.", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { + "get": { + "operationId": "previewCompletionFile", + "tags": [ + "Files" + ], + "summary": "Download File", + "description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier, used for end-user context.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : Access to the requested file is denied.", + "content": { + "application/json": { + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : The requested file was not found.", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "operationId": "getEndUserCompletion", + "tags": [ + "End Users" + ], + "summary": "Get End User Info", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "End user ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "End user retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "Response Example", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : End user not found.", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "completionAudioToText", + "tags": [ + "TTS" + ], + "summary": "Convert Audio to Text", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully converted audio to text.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "Response Example", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : Audio file size exceeded the limit.", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : Audio type is not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, "/text-to-audio": { "post": { - "summary": "Text to Audio", - "description": "Convert text to speech.", "operationId": "textToAudio", - "tags": ["TTS"], + "tags": [ + "TTS" + ], + "summary": "Convert Text to Audio", + "description": "Convert text to speech.", "requestBody": { "required": true, "content": { @@ -483,11 +890,13 @@ "$ref": "#/components/schemas/TextToAudioRequest" }, "examples": { - "example": { + "textToAudioExample": { + "summary": "Request Example", "value": { - "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", - "text": "Hello Dify", - "user": "abc-123" + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false } } } @@ -496,22 +905,78 @@ }, "responses": { "200": { - "description": "Audio file generated successfully.", + "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", "content": { - "audio/wav": { + "audio/mpeg": { "schema": { "type": "string", - "format": "binary", - "description": "The generated audio file in WAV format." + "format": "binary" } } - }, - "headers": { - "Content-Type": { - "description": "The content type of the response, typically `audio/wav` or `audio/mp3` depending on server configuration.", - "schema": { - "type": "string", - "example": "audio/wav" + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } } } } @@ -521,10 +986,12 @@ }, "/info": { "get": { - "summary": "Get Application Basic Information", - "description": "Used to get basic information about this application.", "operationId": "getAppInfo", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App Info", + "description": "Retrieve basic information about this application, including name, description, tags, and mode.", "responses": { "200": { "description": "Basic information of the application.", @@ -534,14 +1001,17 @@ "$ref": "#/components/schemas/AppInfoResponse" }, "examples": { - "success": { + "appInfo": { + "summary": "Response Example", "value": { - "name": "My App", - "description": "This is my app.", + "name": "My Completion App", + "description": "A helpful customer service chatbot.", "tags": [ - "tag1", - "tag2" - ] + "customer-service", + "chatbot" + ], + "mode": "completion", + "author_name": "Dify Team" } } } @@ -553,39 +1023,58 @@ }, "/parameters": { "get": { - "summary": "Get Application Parameters Information", - "description": "Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values.", "operationId": "getAppParameters", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App Parameters", + "description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.", "responses": { "200": { "description": "Application parameters information.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AppParametersResponse" + "$ref": "#/components/schemas/CompletionAppParametersResponse" }, "examples": { - "success": { + "appParameters": { + "summary": "Response Example", "value": { - "opening_statement": "Hello!", + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], "suggested_questions_after_answer": { "enabled": true }, "speech_to_text": { - "enabled": true + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" }, "retriever_resource": { "enabled": true }, "annotation_reply": { - "enabled": true + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false }, "user_input_form": [ { - "paragraph": { - "label": "Query", - "variable": "query", + "text-input": { + "label": "City", + "variable": "city", "required": true, "default": "" } @@ -593,7 +1082,7 @@ ], "file_upload": { "image": { - "enabled": false, + "enabled": true, "number_limits": 3, "detail": "high", "transfer_methods": [ @@ -606,7 +1095,61 @@ "file_size_limit": 15, "image_file_size_limit": 10, "audio_file_size_limit": 50, - "video_file_size_limit": 100 + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : App unavailable or misconfigured.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getCompletionAppMeta", + "tags": [ + "Applications" + ], + "summary": "Get App Meta", + "description": "Retrieve metadata about this application, including tool icons and other configuration details.", + "responses": { + "200": { + "description": "Successfully retrieved application meta information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "Response Example", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } } } } @@ -619,10 +1162,12 @@ }, "/site": { "get": { - "summary": "Get Application WebApp Settings", - "description": "Used to get the WebApp settings of the application.", "operationId": "getWebAppSettings", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App WebApp Settings", + "description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.", "responses": { "200": { "description": "WebApp settings of the application.", @@ -632,22 +1177,40 @@ "$ref": "#/components/schemas/WebAppSettingsResponse" }, "examples": { - "success": { + "webAppSettings": { + "summary": "Response Example", "value": { - "title": "My App", - "chat_color_theme": "#ff4a4a", + "title": "My Chat App", + "chat_color_theme": "#4A90D9", "chat_color_theme_inverted": false, "icon_type": "emoji", - "icon": "😄", - "icon_background": "#FFEAD5", + "icon": "🤖", + "icon_background": "#FFFFFF", "icon_url": null, - "description": "This is my app.", - "copyright": "all rights reserved", - "privacy_policy": "", - "custom_disclaimer": "All generated by AI", + "description": "A helpful customer service chatbot.", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", "default_language": "en-US", "show_workflow_steps": false, - "use_icon_as_answer_icon": false + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Site not found for this application or the workspace has been archived.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." } } } @@ -664,117 +1227,179 @@ "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", - "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with 'Bearer '. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" + } + }, + "responses": { + "SuccessResult": { + "description": "Operation successful.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Result status." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } } }, "schemas": { "CompletionRequest": { "type": "object", + "required": [ + "inputs", + "user" + ], "properties": { "inputs": { "type": "object", - "description": "Allows the entry of various variable values defined by the App. The `inputs` parameter contains multiple key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. The text generation application requires at least one key/value pair to be inputted.", - "required": ["query"], - "properties": { - "query": { - "type": "string", - "description": "The input text, the content to be processed." - } - }, - "additionalProperties": { - "type": "string" - }, - "example": {"query": "Translate 'hello' to Spanish."} + "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", + "additionalProperties": true + }, + "query": { + "type": "string", + "default": "", + "description": "The input text to be processed. This is a legacy parameter; in newer apps, the query should be passed inside the `inputs` object." }, "response_mode": { "type": "string", - "enum": ["streaming", "blocking"], - "description": "The mode of response return.\n- `streaming`: Streaming mode (recommended), implements a typewriter-like output through SSE ([Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)).\n- `blocking`: Blocking mode, returns result after execution is complete. (Requests may be interrupted if the process is long). *Due to Cloudflare restrictions, the request will be interrupted without a return after 100 seconds in blocking mode for long processes.*", - "example": "streaming" + "enum": [ + "streaming", + "blocking" + ], + "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior." }, "user": { "type": "string", - "description": "User identifier, used to define the identity of the end-user for retrieval and statistics. Should be uniquely defined by the developer within the application.", - "example": "user-12345" + "description": "User identifier, unique within the application. This identifier scopes data access — messages and files are only visible when queried with the same `user` value." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, - "description": "File list, suitable for inputting files (images) combined with text understanding and answering questions, available only when the model supports Vision capability." + "description": "File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`." } - }, - "required": [ - "inputs" - ] + } }, "InputFileObject": { "type": "object", - "required": ["type", "transfer_method"], + "required": [ + "type", + "transfer_method" + ], "properties": { "type": { "type": "string", - "enum": ["image"], - "description": "Supported type: `image` (currently only supports image type)." + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "File type." }, "transfer_method": { "type": "string", - "enum": ["remote_url", "local_file"], - "description": "Transfer method, `remote_url` for image URL / `local_file` for file upload" + "enum": [ + "remote_url", + "local_file" + ], + "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file." }, "url": { "type": "string", "format": "url", - "description": "Image URL (when the transfer method is `remote_url`)" + "description": "File URL (when `transfer_method` is `remote_url`)." }, "upload_file_id": { "type": "string", - "description": "Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`)" + "description": "Uploaded file ID, obtained by uploading through the [Upload File](/api-reference/files/upload-file) API in advance (when `transfer_method` is `local_file`)." } }, "anyOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } + "properties": { + "transfer_method": { + "enum": [ + "remote_url" + ] + }, + "url": { + "type": "string", + "format": "url" + } }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "required": [ + "url" + ], + "not": { + "required": [ + "upload_file_id" + ] + } }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } + "properties": { + "transfer_method": { + "enum": [ + "local_file" + ] + }, + "upload_file_id": { + "type": "string" + } }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "required": [ + "upload_file_id" + ], + "not": { + "required": [ + "url" + ] + } } - ], - "example": { - "type": "image", - "transfer_method": "remote_url", - "url": "https://example.com/image.png" - } + ] }, "CompletionResponse": { "type": "object", - "description": "Response object for blocking mode completion.", "properties": { "event": { "type": "string", - "description": "Event type, for blocking mode this is typically 'message'.", - "example": "message" + "description": "Event type, fixed as `message`." + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID for request tracking and the [Stop Completion Message Generation](/api-reference/completions/stop-completion-message-generation) API." + }, + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of this response event." }, "message_id": { "type": "string", "format": "uuid", - "description": "Unique message ID." + "description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints." }, "mode": { "type": "string", - "description": "App mode, fixed as `completion` for this response type (Note: MD also mentions 'chat', using 'completion' from example).", - "example": "completion" + "description": "App mode, fixed as `completion`." }, "answer": { "type": "string", @@ -782,70 +1407,87 @@ }, "metadata": { "type": "object", + "description": "Metadata including usage and retriever resources.", "properties": { "usage": { "$ref": "#/components/schemas/Usage" }, "retriever_resources": { "type": "array", + "description": "List of retriever resources used.", "items": { "$ref": "#/components/schemas/RetrieverResource" - }, - "description": "Citation and Attribution List." + } } } }, "created_at": { "type": "integer", "format": "int64", - "description": "Message creation timestamp (Unix epoch).", - "example": 1705395332 + "description": "Message creation timestamp (Unix epoch seconds)." } } }, "ChunkCompletionEvent": { "type": "object", - "description": "Structure of a Server-Sent Event chunk in streaming mode. The `event` field determines the structure of the rest of the object.", + "properties": { + "event": { + "type": "string", + "enum": [ + "message", + "message_end", + "message_file", + "tts_message", + "tts_message_end", + "message_replace", + "error", + "ping" + ], + "description": "The type of streaming event." + } + }, "discriminator": { "propertyName": "event", "mapping": { "message": "#/components/schemas/StreamEventMessage", "message_end": "#/components/schemas/StreamEventMessageEnd", + "message_file": "#/components/schemas/StreamEventMessageFile", "tts_message": "#/components/schemas/StreamEventTtsMessage", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", "message_replace": "#/components/schemas/StreamEventMessageReplace", "error": "#/components/schemas/StreamEventError", "ping": "#/components/schemas/StreamEventPing" } - }, + } + }, + "StreamEventBase": { + "type": "object", "properties": { - "event": { - "type": "string", - "enum": ["message", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], - "description": "The type of event." - }, "task_id": { "type": "string", "format": "uuid", - "description": "Task ID, used for request tracking and the Stop Generate API. Not present in 'ping' event." + "description": "Task ID." }, "message_id": { "type": "string", "format": "uuid", - "description": "Unique message ID. Not present in 'ping' event." + "description": "Unique message ID." }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp (Unix epoch). Not present in 'ping' event.", - "example": 1705395332 + "description": "Creation timestamp." } - }, - "required": ["event"] + } }, "StreamEventMessage": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "LLM returns text chunk event.", @@ -854,91 +1496,159 @@ "type": "string", "description": "LLM returned text chunk content." } - }, - "required": ["task_id", "message_id", "answer", "created_at"] + } } ] }, "StreamEventMessageEnd": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Message end event, receiving this event means streaming has ended.", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, "metadata": { "type": "object", + "description": "Metadata including usage and retriever resources.", "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, + "usage": { + "$ref": "#/components/schemas/Usage" + }, "retriever_resources": { "type": "array", - "items": { "$ref": "#/components/schemas/RetrieverResource" }, - "description": "Citation and Attribution List." + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } } } } - }, - "required": ["task_id", "message_id", "metadata"] + } } ] }, "StreamEventTtsMessage": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "description": "TTS audio stream event. The content is an audio block in Mp3 format, encoded as a base64 string. (This message is available only when auto-play is enabled)", + "description": "TTS audio stream event (base64 encoded MP3). Available if auto-play is enabled.", "properties": { "audio": { "type": "string", "format": "byte", - "description": "The audio after speech synthesis, encoded in base64 text content. When playing, simply decode the base64 and feed it into the player." + "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." } - }, - "required": ["task_id", "message_id", "audio", "created_at"] + } } ] }, - "StreamEventTtsMessageEnd": { + "StreamEventTtsMessageEnd": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "TTS audio stream end event.", "properties": { "audio": { "type": "string", - "description": "The end event has no audio, so this is an empty string." + "description": "Empty string. Signals the end of the audio stream." } - }, - "required": ["task_id", "message_id", "audio", "created_at"] + } + } + ] + }, + "StreamEventMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "Message file event, a new file created by a tool.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File unique ID." + }, + "type": { + "type": "string", + "description": "File type, e.g. `image`." + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "Who this file belongs to, always `assistant` here." + }, + "url": { + "type": "string", + "format": "url", + "description": "Remote URL of the file." + } + } } ] }, "StreamEventMessageReplace": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "description": "Message content replacement event. When output content moderation is enabled, if the content is flagged, then the message content will be replaced with a preset reply through this event.", + "description": "Message content replacement event (e.g., due to content moderation).", "properties": { "answer": { "type": "string", - "description": "Replacement content (directly replaces all LLM reply text)." + "description": "Replacement content." + }, + "reason": { + "type": "string", + "description": "Reason for the content replacement." } - }, - "required": ["task_id", "message_id", "answer", "created_at"] + } } ] }, "StreamEventError": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "description": "Exceptions that occur during the streaming process will be output in the form of stream events, and reception of an error event will end the stream.", + "description": "Error event during streaming.", "properties": { - "status": { + "status": { "type": "integer", "description": "HTTP status code." }, @@ -950,192 +1660,581 @@ "type": "string", "description": "Error message." } - }, - "required": ["task_id", "message_id", "status", "code", "message"] + } } ] }, "StreamEventPing": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, { "type": "object", - "description": "Ping event every 10 seconds to keep the connection alive. This event type does not contain other fields like task_id or message_id." + "description": "Ping event to keep connection alive." } ] }, "Usage": { "type": "object", - "description": "Model usage information.", "properties": { - "prompt_tokens": { "type": "integer" }, - "prompt_unit_price": { "type": "string", "format": "decimal" }, - "prompt_price_unit": { "type": "string", "format": "decimal" }, - "prompt_price": { "type": "string", "format": "decimal" }, - "completion_tokens": { "type": "integer" }, - "completion_unit_price": { "type": "string", "format": "decimal" }, - "completion_price_unit": { "type": "string", "format": "decimal" }, - "completion_price": { "type": "string", "format": "decimal" }, - "total_tokens": { "type": "integer" }, - "total_price": { "type": "string", "format": "decimal" }, - "currency": { "type": "string", "example": "USD" }, - "latency": { "type": "number", "format": "double" } + "prompt_tokens": { + "type": "integer", + "description": "Number of tokens in the prompt." + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per prompt token." + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for prompt tokens." + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "Total price for prompt tokens." + }, + "completion_tokens": { + "type": "integer", + "description": "Number of tokens in the completion." + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per completion token." + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for completion tokens." + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "Total price for completion tokens." + }, + "total_tokens": { + "type": "integer", + "description": "Total number of tokens used." + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "Total price for all tokens." + }, + "currency": { + "type": "string", + "description": "Currency for pricing." + }, + "latency": { + "type": "number", + "format": "double", + "description": "Latency in seconds." + } } }, "RetrieverResource": { "type": "object", - "description": "Citation and Attribution information for a resource.", "properties": { - "document_id": { "type": "string", "description": "ID of the retrieved document." }, - "segment_id": { "type": "string", "description": "ID of the specific segment within the document." }, - "score": { "type": "number", "format": "float", "description": "Relevance score of the resource." }, - "content": { "type": "string", "description": "Content snippet from the resource." } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of the retriever resource." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "ID of the message this resource belongs to." + }, + "position": { + "type": "integer", + "description": "Position of the resource in the list." + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "ID of the knowledge base." + }, + "dataset_name": { + "type": "string", + "description": "Name of the knowledge base." + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "ID of the document." + }, + "document_name": { + "type": "string", + "description": "Name of the document." + }, + "data_source_type": { + "type": "string", + "description": "Type of the data source." + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "ID of the specific chunk within the document." + }, + "score": { + "type": "number", + "format": "float", + "description": "Relevance score of the resource." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this chunk was hit." + }, + "word_count": { + "type": "integer", + "description": "Word count of the chunk." + }, + "segment_position": { + "type": "integer", + "description": "Position of the chunk within the document." + }, + "index_node_hash": { + "type": "string", + "description": "Hash of the index node." + }, + "content": { + "type": "string", + "description": "Content snippet from the resource." + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary of the chunk content." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." + } } }, "FileUploadResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "ID of the uploaded file." }, - "name": { "type": "string", "description": "File name." }, - "size": { "type": "integer", "description": "File size (bytes)." }, - "extension": { "type": "string", "description": "File extension." }, - "mime_type": { "type": "string", "description": "File mime-type." }, - "created_by": { "type": "string", "format": "uuid", "description": "End-user ID who uploaded the file." }, - "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp (Unix epoch).", "example": 1577836800 } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique file ID." + }, + "name": { + "type": "string", + "description": "File name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "nullable": true, + "description": "File extension." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Upload timestamp (Unix epoch seconds)." + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "Preview URL for the file." + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "Source URL of the file." + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "Original URL of the file." + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated user." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated tenant." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated conversation." + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "Storage key for the file." + } } }, "EndUserDetail": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "Tenant ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Application ID." + }, + "type": { + "type": "string", + "description": "End user type. Always `service_api` for Service API users." + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Completion Message](/api-reference/completions/send-completion-message))." + }, + "name": { + "type": "string", + "nullable": true, + "description": "End user name." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request." + }, + "session_id": { + "type": "string", + "description": "Session identifier. Defaults to the `external_user_id` value." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } } }, "MessageFeedbackRequest": { "type": "object", + "description": "Request body for submitting message feedback.", + "required": [ + "user" + ], "properties": { "rating": { "type": "string", - "enum": ["like", "dislike", null], + "enum": [ + "like", + "dislike", + null + ], "nullable": true, - "description": "Upvote as `like`, downvote as `dislike`, revoke upvote/downvote as `null`." + "description": "Feedback rating. Set to `null` to revoke previously submitted feedback." }, "user": { "type": "string", - "description": "User identifier, defined by the developer's rules, must be unique within the application." + "description": "User identifier, defined by the developer, must ensure uniqueness within the application." }, "content": { "type": "string", - "description": "The specific content of message feedback." + "description": "Optional text feedback providing additional detail." } - }, - "required": ["user"] + } }, "AppFeedbacksResponse": { "type": "object", "properties": { "data": { "type": "array", + "description": "List of feedback items.", "items": { "$ref": "#/components/schemas/FeedbackItem" - }, - "description": "List of application feedback items." + } } } }, "FeedbackItem": { "type": "object", + "description": "A single feedback item.", "properties": { - "id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "message_id": { "type": "string", "format": "uuid" }, - "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, - "content": { "type": "string" }, - "from_source": { "type": "string" }, - "from_end_user_id": { "type": "string", "format": "uuid" }, - "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "Feedback ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "Application ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + }, + "content": { + "type": "string", + "nullable": true, + "description": "Optional text feedback." + }, + "from_source": { + "type": "string", + "description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console." + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "End user ID who submitted the feedback. Present when `from_source` is `user`." + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Account ID who submitted the feedback. Present when `from_source` is `admin`." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "Request body for audio-to-text conversion.", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `30 MB`." + }, + "user": { + "type": "string", + "description": "User identifier." + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "Output text from speech recognition." + } } }, "TextToAudioRequest": { "type": "object", + "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", "properties": { "message_id": { "type": "string", "format": "uuid", - "description": "For text messages generated by Dify, simply pass the generated message-id directly. The backend will use the message-id to look up the corresponding content and synthesize the voice information directly. If both message_id and text are provided simultaneously, the message_id is given priority." + "description": "Message ID. Takes priority over `text` when both are provided." }, "text": { "type": "string", - "description": "Speech generated content. Used if message_id is not provided or not found." + "description": "Speech content to convert." }, "user": { "type": "string", - "description": "The user identifier, defined by the developer, must ensure uniqueness within the app." + "description": "User identifier." + }, + "voice": { + "type": "string", + "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." + }, + "streaming": { + "type": "boolean", + "description": "Whether to enable streaming response." } - }, - "required": ["user"], - "description": "At least one of `message_id` or `text` must be provided, along with `user`." + } }, "AppInfoResponse": { "type": "object", "properties": { - "name": { "type": "string", "description": "Application name." }, - "description": { "type": "string", "description": "Application description." }, + "name": { + "type": "string", + "description": "Application name." + }, + "description": { + "type": "string", + "description": "Application description." + }, "tags": { "type": "array", - "items": { "type": "string" }, + "items": { + "type": "string" + }, "description": "Application tags." + }, + "mode": { + "type": "string", + "description": "Application mode. `completion` for text generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for chatflow apps, `workflow` for workflow apps." + }, + "author_name": { + "type": "string", + "description": "Name of the application author." } } }, - "AppParametersResponse": { + "CompletionAppParametersResponse": { "type": "object", "properties": { - "opening_statement": { "type": "string", "description": "Opening statement." }, + "opening_statement": { + "type": "string", + "description": "Opening statement displayed at start." + }, "suggested_questions": { "type": "array", - "items": { "type": "string" }, - "description": "List of suggested questions for the opening." + "items": { + "type": "string" + }, + "description": "List of suggested starter questions." }, "suggested_questions_after_answer": { "type": "object", + "description": "Configuration for suggested questions after answer.", "properties": { - "enabled": { "type": "boolean", "description": "Whether suggesting questions after an answer is enabled." } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } } }, "speech_to_text": { "type": "object", + "description": "Speech-to-text configuration.", "properties": { - "enabled": { "type": "boolean", "description": "Whether speech to text is enabled." } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "text_to_speech": { + "type": "object", + "description": "Text-to-speech configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + }, + "voice": { + "type": "string", + "description": "Voice identifier for TTS." + }, + "language": { + "type": "string", + "description": "Language for TTS." + }, + "autoPlay": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Auto-play setting." + } } }, "retriever_resource": { "type": "object", + "description": "Retriever resource configuration.", "properties": { - "enabled": { "type": "boolean", "description": "Whether citation and attribution (retriever resource) is enabled." } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } } }, "annotation_reply": { "type": "object", + "description": "Annotation reply configuration.", "properties": { - "enabled": { "type": "boolean", "description": "Whether annotation reply is enabled." } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "more_like_this": { + "type": "object", + "description": "More-like-this configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "Sensitive word avoidance configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } } }, "user_input_form": { "type": "array", - "items": { "$ref": "#/components/schemas/UserInputFormItem" }, - "description": "User input form configuration." + "description": "List of user input form elements.", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } }, "file_upload": { "type": "object", @@ -1143,15 +2242,30 @@ "properties": { "image": { "type": "object", - "description": "Image settings. Currently only supports image types: png, jpg, jpeg, webp, gif.", + "description": "Image upload settings.", "properties": { - "enabled": { "type": "boolean", "description": "Whether image upload is enabled." }, - "number_limits": { "type": "integer", "description": "Image number limit, default is 3." }, - "detail": {"type": "string", "description": "Detail level for image processing (e.g., 'high'). From example, not in main description."}, + "enabled": { + "type": "boolean", + "description": "Whether image upload is enabled." + }, + "number_limits": { + "type": "integer", + "description": "Maximum number of images." + }, + "detail": { + "type": "string", + "description": "Image detail level." + }, "transfer_methods": { "type": "array", - "items": { "type": "string", "enum": ["remote_url", "local_file"] }, - "description": "List of transfer methods, must choose at least one if enabled." + "items": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ] + }, + "description": "Allowed transfer methods." } } } @@ -1159,119 +2273,269 @@ }, "system_parameters": { "type": "object", - "description": "System parameters.", + "description": "System-level parameters and limits.", "properties": { - "file_size_limit": { "type": "integer", "description": "Document upload size limit (MB)." }, - "image_file_size_limit": { "type": "integer", "description": "Image file upload size limit (MB)." }, - "audio_file_size_limit": { "type": "integer", "description": "Audio file upload size limit (MB)." }, - "video_file_size_limit": { "type": "integer", "description": "Video file upload size limit (MB)." } + "file_size_limit": { + "type": "integer", + "description": "Maximum file size in MB." + }, + "image_file_size_limit": { + "type": "integer", + "description": "Maximum image file size in MB." + }, + "audio_file_size_limit": { + "type": "integer", + "description": "Maximum audio file size in MB." + }, + "video_file_size_limit": { + "type": "integer", + "description": "Maximum video file size in MB." + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "Maximum number of files for workflow file upload." + } } } } }, "UserInputFormItem": { "type": "object", - "description": "Represents a single item in the user input form. It will have one of the specific control type keys.", "oneOf": [ - { "$ref": "#/components/schemas/TextInputControlWrapper" }, - { "$ref": "#/components/schemas/ParagraphControlWrapper" }, - { "$ref": "#/components/schemas/SelectControlWrapper" } + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } ] }, "TextInputControlWrapper": { + "title": "Text Input", "type": "object", "properties": { - "text-input": { "$ref": "#/components/schemas/TextInputControl" } - }, - "required": ["text-input"] + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } }, "ParagraphControlWrapper": { + "title": "Paragraph", "type": "object", "properties": { - "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } - }, - "required": ["paragraph"] + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } }, "SelectControlWrapper": { + "title": "Select", "type": "object", "properties": { - "select": { "$ref": "#/components/schemas/SelectControl" } - }, - "required": ["select"] + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } }, "TextInputControl": { "type": "object", - "description": "Text input control.", "properties": { - "label": { "type": "string", "description": "Variable display label name." }, - "variable": { "type": "string", "description": "Variable ID." }, - "required": { "type": "boolean", "description": "Whether it is required." }, - "default": { "type": "string", "description": "Default value." } - }, - "required": ["label", "variable", "required"] + "label": { + "type": "string", + "description": "Display label for the form field." + }, + "variable": { + "type": "string", + "description": "Variable name used as the key in the `inputs` object." + }, + "required": { + "type": "boolean", + "description": "Whether this field must be filled before submission." + }, + "default": { + "type": "string", + "description": "Default value pre-filled in the form field." + } + } }, "ParagraphControl": { "type": "object", - "description": "Paragraph text input control.", "properties": { - "label": { "type": "string", "description": "Variable display label name." }, - "variable": { "type": "string", "description": "Variable ID." }, - "required": { "type": "boolean", "description": "Whether it is required." }, - "default": { "type": "string", "description": "Default value." } - }, - "required": ["label", "variable", "required"] + "label": { + "type": "string", + "description": "Display label for the form field." + }, + "variable": { + "type": "string", + "description": "Variable name used as the key in the `inputs` object." + }, + "required": { + "type": "boolean", + "description": "Whether this field must be filled before submission." + }, + "default": { + "type": "string", + "description": "Default value pre-filled in the form field." + } + } }, "SelectControl": { "type": "object", - "description": "Dropdown control.", "properties": { - "label": { "type": "string", "description": "Variable display label name." }, - "variable": { "type": "string", "description": "Variable ID." }, - "required": { "type": "boolean", "description": "Whether it is required." }, - "default": { "type": "string", "description": "Default value." }, + "label": { + "type": "string", + "description": "Display label for the form field." + }, + "variable": { + "type": "string", + "description": "Variable name used as the key in the `inputs` object." + }, + "required": { + "type": "boolean", + "description": "Whether a selection must be made before submission." + }, + "default": { + "type": "string", + "description": "Default selected value." + }, "options": { "type": "array", - "items": { "type": "string" }, - "description": "Option values." + "items": { + "type": "string" + }, + "description": "List of selectable values for this form control." } - }, - "required": ["label", "variable", "required", "options"] + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "URL of the icon." + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "Tool icons. Keys are tool names." + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "Detail of a tool icon using emoji.", + "properties": { + "background": { + "type": "string", + "description": "Background color in hex format." + }, + "content": { + "type": "string", + "description": "Emoji content." + } + } }, "WebAppSettingsResponse": { "type": "object", "properties": { - "title": { "type": "string", "description": "WebApp name." }, - "chat_color_theme": { "type": "string", "description": "Chat color theme, in hex format (e.g., #RRGGBB)." }, - "chat_color_theme_inverted": { "type": "boolean", "description": "Whether the chat color theme is inverted." }, - "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "Icon type." }, - "icon": { "type": "string", "description": "Icon. If it's `emoji` type, it's an emoji symbol; if it's `image` type, it's an image URL." }, - "icon_background": { "type": "string", "description": "Background color in hex format (e.g., #RRGGBB)." }, - "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "Icon URL (likely refers to image type if `icon` field is just a name/id)." }, - "description": { "type": "string", "description": "Description." }, - "copyright": { "type": "string", "description": "Copyright information." }, - "privacy_policy": { "type": "string", "description": "Privacy policy link." }, - "custom_disclaimer": { "type": "string", "description": "Custom disclaimer." }, - "default_language": { "type": "string", "description": "Default language (e.g., en-US)." }, - "show_workflow_steps": { "type": "boolean", "description": "Whether to show workflow details." }, - "use_icon_as_answer_icon": { "type": "boolean", "description": "Whether to replace 🤖 in chat with the WebApp icon." } - } - }, - "ErrorResponse": { - "type": "object", - "properties": { - "status": { "type": "integer", "description": "HTTP status code." }, - "code": { "type": "string", "description": "Error code specific to the application." }, - "message": { "type": "string", "description": "A human-readable error message." } + "title": { + "type": "string", + "description": "WebApp title." + }, + "chat_color_theme": { + "type": "string", + "description": "Chat color theme." + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "Whether the chat color theme is inverted." + }, + "icon_type": { + "type": "string", + "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." + }, + "icon": { + "type": "string", + "description": "Icon content (emoji or image ID)." + }, + "icon_background": { + "type": "string", + "description": "Icon background color." + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "URL of the icon image." + }, + "description": { + "type": "string", + "description": "WebApp description." + }, + "copyright": { + "type": "string", + "description": "Copyright text." + }, + "privacy_policy": { + "type": "string", + "description": "Privacy policy URL." + }, + "custom_disclaimer": { + "type": "string", + "description": "Custom disclaimer text." + }, + "default_language": { + "type": "string", + "description": "Default language code." + }, + "show_workflow_steps": { + "type": "boolean", + "description": "Whether to show workflow steps." + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "Whether to use the app icon as the answer icon." + } } } } }, "tags": [ - { "name": "Completion", "description": "Operations related to text generation and completion." }, - { "name": "Files", "description": "Operations related to file management." }, - { "name": "End Users", "description": "Operations related to end user information." }, - { "name": "Feedback", "description": "Operations related to user feedback." }, - { "name": "TTS", "description": "Operations related to Text-to-Speech." }, - { "name": "Application", "description": "Operations to retrieve application settings and information." } + { + "name": "Completions", + "description": "Operations related to text generation and completion." + }, + { + "name": "Files", + "description": "Operations related to file management." + }, + { + "name": "End Users", + "description": "Operations related to end user information." + }, + { + "name": "Feedback", + "description": "Operations related to user feedback." + }, + { + "name": "TTS", + "description": "Operations related to Text-to-Speech and Speech-to-Text." + }, + { + "name": "Applications", + "description": "Operations to retrieve application settings and information." + } ] } diff --git a/en/api-reference/openapi_knowledge.json b/en/api-reference/openapi_knowledge.json index f1737651..a65fa30e 100644 --- a/en/api-reference/openapi_knowledge.json +++ b/en/api-reference/openapi_knowledge.json @@ -2,7 +2,7 @@ "openapi": "3.0.1", "info": { "title": "Knowledge API", - "description": "API for managing knowledge bases (datasets), documents, and segments, including creation, retrieval, and configuration.", + "description": "API for managing knowledge bases, documents, chunks, metadata, and tags, including creation, retrieval, and configuration. **Note:** A single Knowledge Base API key has permission to operate on all visible knowledge bases under the same account. Please pay attention to data security.", "version": "1.0.0" }, "servers": [ @@ -24,81 +24,271 @@ ], "tags": [ { - "name": "Datasets", - "description": "Operations related to managing knowledge bases (datasets)." + "name": "Knowledge Bases", + "description": "Operations for managing knowledge bases, including creation, configuration, and retrieval." }, { "name": "Documents", - "description": "Operations for creating, updating, and managing documents within a dataset." + "description": "Operations for creating, updating, and managing documents within a knowledge base." }, { "name": "Chunks", - "description": "Operations for managing document chunks (segments)." + "description": "Operations for managing document chunks and child chunks." }, { - "name": "Metadata & Tags", - "description": "Operations for managing dataset tags and metadata." + "name": "Metadata", + "description": "Operations for managing knowledge base metadata fields and document metadata values." + }, + { + "name": "Tags", + "description": "Operations for managing knowledge base tags and tag bindings." }, { "name": "Models", "description": "Operations for retrieving available models." + }, + { + "name": "Knowledge Pipeline", + "description": "Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution." } ], "paths": { "/datasets": { "post": { "tags": [ - "Datasets" + "Knowledge Bases" ], "summary": "Create an Empty Knowledge Base", - "description": "Creates a new, empty knowledge base (dataset) with specified configurations.", + "description": "Create a new empty knowledge base. After creation, use [Create Document by Text](/api-reference/documents/create-document-by-text) or [Create Document by File](/api-reference/documents/create-document-by-file) to add documents.", "operationId": "createDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateDatasetRequest" + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "Name of the knowledge base." + }, + "description": { + "type": "string", + "maxLength": 400, + "default": "", + "description": "Description of the knowledge base." + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "default": "only_me", + "description": "Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members." + }, + "provider": { + "type": "string", + "enum": [ + "vendor", + "external" + ], + "default": "vendor", + "description": "`vendor` for internal knowledge base, `external` for external knowledge base." + }, + "embedding_model": { + "type": "string", + "description": "Embedding model name. Use the `model` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "embedding_model_provider": { + "type": "string", + "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + }, + "external_knowledge_api_id": { + "type": "string", + "description": "ID of the external knowledge API connection." + }, + "external_knowledge_id": { + "type": "string", + "description": "ID of the external knowledge base." + }, + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "Summary index configuration.", + "properties": { + "enable": { + "type": "boolean", + "description": "Whether to enable summary indexing." + }, + "model_name": { + "type": "string", + "description": "Name of the model used for generating summaries." + }, + "model_provider_name": { + "type": "string", + "description": "Provider of the summary generation model." + }, + "summary_prompt": { + "type": "string", + "description": "Custom prompt template for summary generation." + } + } + } + } } } } }, "responses": { "200": { - "description": "Successfully created dataset.", + "description": "Knowledge base created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "Technical documentation for the product API", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "description": "`dataset_name_duplicate` : The dataset name already exists. Please modify your dataset name.", + "content": { + "application/json": { + "examples": { + "dataset_name_duplicate": { + "summary": "dataset_name_duplicate", + "value": { + "status": 409, + "code": "dataset_name_duplicate", + "message": "The dataset name already exists. Please modify your dataset name." + } + } + } + } + } } } }, "get": { "tags": [ - "Datasets" + "Knowledge Bases" ], - "summary": "Get Knowledge Base List", - "description": "Retrieves a list of knowledge bases, with options for pagination and filtering.", + "summary": "List Knowledge Bases", + "description": "Returns a paginated list of knowledge bases. Supports filtering by keyword and tags.", "operationId": "listDatasets", "parameters": [ + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "description": "Page number to retrieve." + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "Number of items per page." + }, { "name": "keyword", "in": "query", - "description": "Search keyword to filter datasets by name.", "schema": { "type": "string" - } + }, + "description": "Search keyword to filter by name." + }, + { + "name": "include_all", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Whether to include all knowledge bases regardless of permissions." }, { "name": "tag_ids", "in": "query", - "description": "List of tag IDs to filter by. Datasets must have all specified tags.", "schema": { "type": "array", "items": { @@ -106,45 +296,104 @@ } }, "style": "form", - "explode": false - }, - { - "name": "page", - "in": "query", - "description": "Page number for pagination.", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "Number of items to return per page.", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } - }, - { - "name": "include_all", - "in": "query", - "description": "Whether to include all datasets. This is effective only for workspace owners.", - "schema": { - "type": "boolean", - "default": false - } + "explode": true, + "description": "Tag IDs to filter by." } ], "responses": { "200": { - "description": "A paginated list of datasets.", + "description": "List of knowledge bases.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "Array of knowledge base objects.", + "items": { + "$ref": "#/components/schemas/Dataset" + } + }, + "has_more": { + "type": "boolean", + "description": "Whether more items exist on the next page." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of matching items." + }, + "page": { + "type": "integer", + "description": "Current page number." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "Technical documentation for the product API", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } } } } @@ -155,30 +404,118 @@ "/datasets/{dataset_id}": { "get": { "tags": [ - "Datasets" + "Knowledge Bases" ], - "summary": "Get Knowledge Base Details", - "description": "Fetches the detailed information of a specific knowledge base by its ID.", + "summary": "Get Knowledge Base", + "description": "Retrieve detailed information about a specific knowledge base, including its embedding model, retrieval configuration, and document statistics.", "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The unique identifier of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "responses": { "200": { - "description": "Detailed information about the dataset.", + "description": "Knowledge base details.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "Technical documentation for the product API", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Insufficient permissions to access this knowledge base.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } } } } @@ -187,21 +524,21 @@ }, "patch": { "tags": [ - "Datasets" + "Knowledge Bases" ], "summary": "Update Knowledge Base", - "description": "Updates the settings of a specific knowledge base.", + "description": "Update the name, description, permissions, or retrieval settings of an existing knowledge base. Only the fields provided in the request body are updated.", "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The unique identifier of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "requestBody": { @@ -209,49 +546,250 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateDatasetRequest" + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "Name of the knowledge base." + }, + "description": { + "type": "string", + "maxLength": 400, + "description": "Description of the knowledge base." + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "description": "Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members." + }, + "embedding_model": { + "type": "string", + "description": "Embedding model name. Use the `model` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "embedding_model_provider": { + "type": "string", + "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + }, + "partial_member_list": { + "type": "array", + "description": "List of team members with access when `permission` is `partial_members`.", + "items": { + "type": "object", + "properties": { + "user_id": { + "type": "string", + "description": "ID of the team member to grant access." + } + } + } + }, + "external_retrieval_model": { + "type": "object", + "description": "Retrieval settings for external knowledge bases.", + "properties": { + "top_k": { + "type": "integer", + "description": "Maximum number of results to return." + }, + "score_threshold": { + "type": "number", + "description": "Minimum relevance score threshold for filtering results." + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + } + } + }, + "external_knowledge_id": { + "type": "string", + "description": "ID of the external knowledge base." + }, + "external_knowledge_api_id": { + "type": "string", + "description": "ID of the external knowledge API connection." + } + } } } } }, "responses": { "200": { - "description": "Successfully updated dataset details.", + "description": "Knowledge base updated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "Technical documentation for the product API", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, - "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "403": { + "description": "`forbidden` : Insufficient permissions to access this knowledge base.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } }, "delete": { "tags": [ - "Datasets" + "Knowledge Bases" ], - "summary": "Delete a Knowledge Base", - "description": "Deletes a knowledge base and all its associated documents and data.", + "summary": "Delete Knowledge Base", + "description": "Permanently delete a knowledge base and all its documents. The knowledge base must not be in use by any application.", "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The unique identifier of the knowledge base to delete.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "responses": { "204": { - "description": "Successfully deleted the dataset." + "description": "Success." + }, + "404": { + "description": "`not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "409": { + "description": "`dataset_in_use` : The knowledge base is being used by some apps. Please remove it from the apps before deleting.", + "content": { + "application/json": { + "examples": { + "dataset_in_use": { + "summary": "dataset_in_use", + "value": { + "status": 409, + "code": "dataset_in_use", + "message": "The dataset is being used by some apps. Please remove the dataset from the apps before deleting it." + } + } + } + } + } } } } @@ -261,19 +799,19 @@ "tags": [ "Documents" ], - "summary": "Create a Document from Text", - "description": "Creates a new document within an existing knowledge base directly from text content.", + "summary": "Create Document by Text", + "description": "Create a document from raw text content. The document is processed asynchronously — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base to add the document to.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "requestBody": { @@ -281,18 +819,222 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateDocumentByTextRequest" + "type": "object", + "required": [ + "name", + "text" + ], + "properties": { + "name": { + "type": "string", + "description": "Document name." + }, + "text": { + "type": "string", + "description": "Document text content." + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "description": "Required when adding the first document to a knowledge base. Subsequent documents inherit the knowledge base's indexing technique if omitted. `high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction." + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "Language of the document for processing optimization." + }, + "process_rule": { + "type": "object", + "description": "Processing rules for chunking.", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "Processing mode. `automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`)." + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "Rule identifier." + }, + "enabled": { + "type": "boolean", + "description": "Whether this preprocessing rule is enabled." + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "Custom separator for splitting text." + }, + "max_tokens": { + "type": "integer", + "description": "Maximum token count per chunk." + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "Token overlap between chunks." + } + } + } + } + } + } + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + }, + "embedding_model": { + "type": "string", + "description": "Embedding model name. Use the `model` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "embedding_model_provider": { + "type": "string", + "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "original_document_id": { + "type": "string", + "description": "Original document ID for versioning." + } + } } } } }, "responses": { "200": { - "description": "Document created successfully and is being indexed.", + "description": "Document created successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "Batch ID for tracking indexing progress." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist. / indexing_technique is required.", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + } } } } @@ -305,19 +1047,19 @@ "tags": [ "Documents" ], - "summary": "Create a Document from a File", - "description": "Creates a new document within an existing knowledge base by uploading a file.", + "summary": "Create Document by File", + "description": "Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base to add the document to.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "requestBody": { @@ -326,16 +1068,19 @@ "multipart/form-data": { "schema": { "type": "object", + "required": [ + "file" + ], "properties": { - "data": { - "type": "string", - "description": "A JSON string containing document metadata and processing rules. See `CreateDocumentByFileRequestData` schema for details.", - "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\": {\"separator\":\"###\", \"max_tokens\":500}}},\"summary_index_setting\":{\"enable\":true,\"model_name\":\"qwen-vl-plus\",\"model_provider_name\":\"langgenius/tongyi/tongyi\",\"summary_prompt\":\"summarize the text\"}}" - }, "file": { "type": "string", "format": "binary", - "description": "The file to upload." + "description": "File to upload." + }, + "data": { + "type": "string", + "description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/api-reference/documents/create-document-by-text) (`indexing_technique`, `doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } @@ -344,179 +1089,228 @@ }, "responses": { "200": { - "description": "Document created successfully and is being indexed.", + "description": "Document created successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "Batch ID for tracking indexing progress." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } } } } }, "400": { - "$ref": "#/components/responses/FileError" - }, - "413": { - "$ref": "#/components/responses/FileTooLarge" - }, - "415": { - "$ref": "#/components/responses/UnsupportedFileType" - } - } - } - }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { - "post": { - "tags": [ - "Documents" - ], - "summary": "Update a Document with Text", - "description": "Updates an existing document's content or settings using text.", - "operationId": "updateDocumentByText", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "The ID of the knowledge base containing the document.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "The ID of the document to update.", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateDocumentByTextRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Document updated successfully.", + "description": "- `no_file_uploaded` : Please upload your file.\n- `too_many_files` : Only one file is allowed.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist, external datasets not supported, file too large, unsupported file type, or missing required fields.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" - } - } - } - } - } - } - }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { - "post": { - "tags": [ - "Documents" - ], - "summary": "Update a Document with a File", - "description": "Updates an existing document by uploading a new file, replacing its content.", - "operationId": "updateDocumentByFile", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "The ID of the knowledge base containing the document.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "The ID of the document to update.", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "string", - "description": "A JSON string containing optional document name and processing rules. See `UpdateDocumentByFileRequestData` schema.", - "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } }, - "file": { - "type": "string", - "format": "binary", - "description": "The new file to upload." + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param (indexing_technique)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + }, + "invalid_param_process_rule": { + "summary": "invalid_param (process_rule)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "process_rule is required." + } } } } } } - }, - "responses": { - "200": { - "description": "Document updated successfully.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" - } - } - } - } } } }, - "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "/datasets/{dataset_id}/documents": { "get": { "tags": [ "Documents" ], - "summary": "Get Document Embedding Status (Progress)", - "description": "Retrieves the indexing status for a batch of documents, showing the progress of embedding and processing.", - "operationId": "getDocumentIndexingStatus", + "summary": "List Documents", + "description": "Returns a paginated list of documents in the knowledge base. Supports filtering by keyword and indexing status.", + "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { - "name": "batch", - "in": "path", - "required": true, - "description": "The batch number returned from the document creation endpoint.", + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "description": "Page number to retrieve." + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "Number of items per page. Server caps at `100`." + }, + { + "name": "keyword", + "in": "query", "schema": { "type": "string" - } + }, + "description": "Search keyword to filter by document name." + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "queuing", + "indexing", + "paused", + "error", + "available", + "disabled", + "archived" + ] + }, + "description": "Filter by display status." } ], "responses": { "200": { - "description": "Indexing status of the documents in the batch.", + "description": "List of documents.", "content": { "application/json": { "schema": { @@ -524,9 +1318,94 @@ "properties": { "data": { "type": "array", + "description": "Array of knowledge base objects.", "items": { - "$ref": "#/components/schemas/IndexingStatus" + "$ref": "#/components/schemas/Document" } + }, + "has_more": { + "type": "boolean", + "description": "Whether more items exist on the next page." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of matching items." + }, + "page": { + "type": "integer", + "description": "Current page number." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Knowledge base not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." } } } @@ -541,34 +1420,33 @@ "tags": [ "Documents" ], - "summary": "Get Document Detail", - "description": "Retrieves detailed information about a single document, including its processing rules and status.", + "summary": "Get Document", + "description": "Retrieve detailed information about a specific document, including its indexing status, metadata, and processing statistics.", "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "metadata", "in": "query", - "description": "Metadata filter: `all` returns all metadata, `only` returns only custom metadata, `without` returns no metadata.", "schema": { "type": "string", "enum": [ @@ -577,16 +1455,281 @@ "without" ], "default": "all" - } + }, + "description": "`all` returns all fields including metadata. `only` returns only `id`, `doc_type`, and `doc_metadata`. `without` returns all fields except `doc_metadata`." } ], "responses": { "200": { - "description": "Detailed information about the document.", + "description": "Document details. The response shape varies based on the `metadata` query parameter. When `metadata` is `only`, only `id`, `doc_type`, and `doc_metadata` are returned. When `metadata` is `without`, `doc_type` and `doc_metadata` are omitted.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentDetail" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Document identifier." + }, + "position": { + "type": "integer", + "description": "Position index within the knowledge base." + }, + "data_source_type": { + "type": "string", + "description": "How the document was uploaded. `upload_file` for file uploads, `notion_import` for Notion imports." + }, + "data_source_info": { + "type": "object", + "description": "Raw data source information." + }, + "dataset_process_rule_id": { + "type": "string", + "description": "ID of the processing rule applied to this document." + }, + "dataset_process_rule": { + "type": "object", + "description": "Knowledge-base-level processing rule configuration." + }, + "document_process_rule": { + "type": "object", + "description": "Document-level processing rule configuration." + }, + "name": { + "type": "string", + "description": "Document name." + }, + "created_from": { + "type": "string", + "description": "Origin of the document. `api` for API creation, `web` for UI creation." + }, + "created_by": { + "type": "string", + "description": "ID of the user who created the document." + }, + "created_at": { + "type": "number", + "description": "Unix timestamp of document creation." + }, + "tokens": { + "type": "integer", + "description": "Number of tokens in the document." + }, + "indexing_status": { + "type": "string", + "description": "Current indexing status, e.g. `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, `error`, `paused`." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if indexing failed, `null` otherwise." + }, + "enabled": { + "type": "boolean", + "description": "Whether the document is enabled for retrieval." + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "Unix timestamp when the document was disabled, `null` if enabled." + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "ID of the user who disabled the document, `null` if enabled." + }, + "archived": { + "type": "boolean", + "description": "Whether the document is archived." + }, + "display_status": { + "type": "string", + "description": "Display-friendly indexing status for the UI." + }, + "word_count": { + "type": "integer", + "description": "Total word count of the document." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this document has been retrieved." + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode. `text_model` for standard text, `hierarchical_model` for parent-child, `qa_model` for QA pairs." + }, + "doc_language": { + "type": "string", + "description": "Language of the document content." + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "Document type classification, `null` if not set." + }, + "doc_metadata": { + "type": "array", + "description": "Custom metadata key-value pairs for this document.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field type." + }, + "value": { + "type": "string", + "description": "Metadata field value for this document." + } + } + } + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "Unix timestamp when processing completed, `null` if not yet completed." + }, + "updated_at": { + "type": "number", + "nullable": true, + "description": "Unix timestamp of last update, `null` if never updated." + }, + "indexing_latency": { + "type": "number", + "nullable": true, + "description": "Time taken for indexing in seconds, `null` if not completed." + }, + "segment_count": { + "type": "integer", + "description": "Number of chunks in the document." + }, + "average_segment_length": { + "type": "number", + "description": "Average character length of chunks." + }, + "summary_index_status": { + "type": "string", + "nullable": true, + "description": "Status of summary indexing, `null` if summary index is not enabled." + }, + "need_summary": { + "type": "boolean", + "description": "Whether the document needs summary generation." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "dataset_process_rule": { + "id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "mode": "custom" + }, + "document_process_rule": { + "mode": "custom", + "rules": { + "pre_processing_rules": [], + "segmentation": { + "separator": "###", + "max_tokens": 500, + "chunk_overlap": 50 + } + } + }, + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_language": "English", + "doc_type": null, + "doc_metadata": [], + "completed_at": 1741267260, + "updated_at": 1741267260, + "indexing_latency": 60.0, + "segment_count": 5, + "average_segment_length": 70.0, + "summary_index_status": null, + "need_summary": false + } + } + } + } + } + }, + "400": { + "description": "`invalid_metadata` : Invalid metadata value for the specified key.", + "content": { + "application/json": { + "examples": { + "invalid_metadata": { + "summary": "invalid_metadata", + "value": { + "status": 400, + "code": "invalid_metadata", + "message": "Invalid metadata value: {metadata_key}" + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : No permission.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Document not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } @@ -597,93 +1740,82 @@ "tags": [ "Documents" ], - "summary": "Delete a Document", - "description": "Deletes a specific document from a knowledge base.", + "summary": "Delete Document", + "description": "Permanently delete a document and all its chunks from the knowledge base.", "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document to delete.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "responses": { "204": { - "description": "Successfully deleted the document." - } - } - } - }, - "/datasets/{dataset_id}/documents": { - "get": { - "tags": [ - "Documents" - ], - "summary": "Get the Document List of a Knowledge Base", - "description": "Retrieves a paginated list of all documents within a specified knowledge base.", - "operationId": "listDocuments", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "The ID of the knowledge base.", - "schema": { - "type": "string", - "format": "uuid" - } + "description": "Success." }, - { - "name": "keyword", - "in": "query", - "description": "Keyword to search for in document names.", - "schema": { - "type": "string" - } - }, - { - "name": "page", - "in": "query", - "description": "Page number for pagination.", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "Number of items to return per page.", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } - } - ], - "responses": { - "200": { - "description": "A paginated list of documents.", + "400": { + "description": "`document_indexing` : Cannot delete document during indexing.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentListResponse" + "examples": { + "document_indexing": { + "summary": "document_indexing", + "value": { + "status": 400, + "code": "document_indexing", + "message": "Cannot delete document during indexing." + } + } + } + } + } + }, + "403": { + "description": "`archived_document_immutable` : The archived document is not editable.", + "content": { + "application/json": { + "examples": { + "archived_document_immutable": { + "summary": "archived_document_immutable", + "value": { + "status": 403, + "code": "archived_document_immutable", + "message": "The archived document is not editable." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Document Not Exists.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document Not Exists." + } + } } } } @@ -691,39 +1823,689 @@ } } }, - "/datasets/{dataset_id}/documents/status/{action}": { - "patch": { + "/datasets/{dataset_id}/documents/{document_id}/download": { + "get": { "tags": [ "Documents" ], - "summary": "Update Document Status", - "description": "Performs a batch action to update the status of one or more documents (e.g., enable, disable, archive).", - "operationId": "batchUpdateDocumentStatus", + "summary": "Download Document", + "description": "Get a signed download URL for a document's original uploaded file.", + "operationId": "downloadDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { - "name": "action", + "name": "document_id", "in": "path", "required": true, - "description": "The action to perform on the documents.", "schema": { "type": "string", - "enum": [ - "enable", - "disable", - "archive", - "un_archive" - ] + "format": "uuid" + }, + "description": "Document ID." + } + ], + "responses": { + "200": { + "description": "Download URL generated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "Signed URL to download the original uploaded file." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600" + } + } + } + } } + }, + "403": { + "description": "`forbidden` : No permission to access this document.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Document not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "get": { + "tags": [ + "Documents" + ], + "summary": "Get Document Indexing Status", + "description": "Check the indexing progress of documents in a batch. Returns the current processing stage and chunk completion counts for each document. Poll this endpoint until `indexing_status` reaches `completed` or `error`. The status progresses through: `waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`.", + "operationId": "getDocumentIndexingStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "batch", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Batch ID returned from document creation." + } + ], + "responses": { + "200": { + "description": "Indexing status for documents in the batch.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "List of indexing status entries.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Document identifier." + }, + "indexing_status": { + "type": "string", + "description": "Current indexing status: `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, or `error`." + }, + "processing_started_at": { + "type": "number", + "description": "Unix timestamp when processing started." + }, + "parsing_completed_at": { + "type": "number", + "description": "Unix timestamp when parsing completed." + }, + "cleaning_completed_at": { + "type": "number", + "description": "Unix timestamp when cleaning completed." + }, + "splitting_completed_at": { + "type": "number", + "description": "Unix timestamp when splitting completed." + }, + "completed_at": { + "type": "number", + "description": "Unix timestamp when indexing completed." + }, + "paused_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing was paused. `null` if not paused." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if indexing failed. `null` if no error." + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing was stopped. `null` if not stopped." + }, + "completed_segments": { + "type": "integer", + "description": "Number of chunks that have been indexed." + }, + "total_segments": { + "type": "integer", + "description": "Total number of chunks to be indexed." + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "indexing_status": "completed", + "processing_started_at": 1741267200, + "parsing_completed_at": 1741267200, + "cleaning_completed_at": 1741267200, + "splitting_completed_at": 1741267200, + "completed_at": 1741267200, + "paused_at": null, + "error": null, + "stopped_at": null, + "completed_segments": 5, + "total_segments": 5 + } + ] + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Knowledge base not found. / Documents not found.", + "content": { + "application/json": { + "examples": { + "dataset_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + }, + "documents_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Documents not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { + "post": { + "tags": [ + "Documents" + ], + "summary": "Update Document by Text", + "description": "Update an existing document's text content, name, or processing configuration. Re-triggers indexing if content changes — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", + "operationId": "updateDocumentByText", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Document name. Required when `text` is provided." + }, + "text": { + "type": "string", + "description": "Document text content." + }, + "process_rule": { + "type": "object", + "description": "Processing rules for chunking.", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "Processing mode. `automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`)." + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "Rule identifier." + }, + "enabled": { + "type": "boolean", + "description": "Whether this preprocessing rule is enabled." + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "Custom separator for splitting text." + }, + "max_tokens": { + "type": "integer", + "description": "Maximum token count per chunk." + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "Token overlap between chunks." + } + } + } + } + } + } + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction." + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "Language of the document for processing optimization." + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Document updated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "Batch ID for tracking indexing progress." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist, or name is required when text is provided.", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_name_required": { + "summary": "invalid_param (name required)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "name is required when text is provided." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { + "post": { + "tags": [ + "Documents" + ], + "summary": "Update Document by File", + "description": "Update an existing document by uploading a new file. Re-triggers indexing — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", + "operationId": "updateDocumentByFile", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "File to upload." + }, + "data": { + "type": "string", + "description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/api-reference/documents/create-document-by-text) (`indexing_technique`, `doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Document updated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "Batch ID for tracking indexing progress." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `too_many_files` : Only one file is allowed.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist, external datasets not supported, file too large, or unsupported file type.", + "content": { + "application/json": { + "examples": { + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/download-zip": { + "post": { + "tags": [ + "Documents" + ], + "summary": "Download Documents as ZIP", + "description": "Download multiple uploaded-file documents as a single ZIP archive. Accepts up to `100` document IDs.", + "operationId": "downloadDocumentsZip", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." } ], "requestBody": { @@ -738,11 +2520,13 @@ "properties": { "document_ids": { "type": "array", - "description": "A list of document IDs to perform the action on.", + "minItems": 1, + "maxItems": 100, "items": { "type": "string", "format": "uuid" - } + }, + "description": "Array of document IDs to include in the ZIP archive." } } } @@ -751,7 +2535,186 @@ }, "responses": { "200": { - "$ref": "#/components/responses/Success" + "description": "ZIP archive containing the requested documents.", + "content": { + "application/zip": { + "schema": { + "type": "string", + "format": "binary", + "description": "ZIP archive binary stream." + } + } + } + }, + "403": { + "description": "`forbidden` : Insufficient permissions.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Document or dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/status/{action}": { + "patch": { + "tags": [ + "Documents" + ], + "summary": "Update Document Status in Batch", + "description": "Enable, disable, archive, or unarchive multiple documents at once.", + "operationId": "batchUpdateDocumentStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable", + "archive", + "un_archive" + ] + }, + "description": "`enable` to activate, `disable` to deactivate, `archive` to archive, `un_archive` to restore from archive." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of document IDs to update." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Documents updated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Operation result." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + }, + "400": { + "description": "`invalid_action` : Invalid action.", + "content": { + "application/json": { + "examples": { + "invalid_action": { + "summary": "invalid_action", + "value": { + "status": 400, + "code": "invalid_action", + "message": "Invalid action." + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Insufficient permissions.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Knowledge base not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } } @@ -761,29 +2724,29 @@ "tags": [ "Chunks" ], - "summary": "Add Chunks to a Document", - "description": "Adds one or more new chunks (segments) to a specific document. This is useful for manually adding curated content.", + "summary": "Create Chunks", + "description": "Create one or more chunks within a document. Each chunk can include optional keywords and an answer field (for QA-mode documents).", "operationId": "createSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "requestBody": { @@ -791,18 +2754,135 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateSegmentsRequest" + "type": "object", + "required": [ + "segments" + ], + "properties": { + "segments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "Chunk text content." + }, + "answer": { + "type": "string", + "description": "Answer content for QA mode." + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Keywords for the chunk." + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Attachment file IDs." + } + } + }, + "description": "Array of chunk objects to create." + } + } } } } }, "responses": { "200": { - "description": "List of newly created segments.", + "description": "Chunks created successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "List of created chunks.", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode used by this document." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model" + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Document is not completed or is disabled.", + "content": { + "application/json": { + "examples": { + "not_found_not_completed": { + "summary": "not_found (not completed)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is not completed." + } + }, + "not_found_disabled": { + "summary": "not_found (disabled)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is disabled." + } + } } } } @@ -813,75 +2893,153 @@ "tags": [ "Chunks" ], - "summary": "Get Chunks from a Document", - "description": "Retrieves a paginated list of chunks (segments) from a specific document.", + "summary": "List Chunks", + "description": "Returns a paginated list of chunks within a document. Supports filtering by keyword and status.", "operationId": "listSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } - }, - { - "name": "keyword", - "in": "query", - "description": "Keyword to filter segments by content.", - "schema": { - "type": "string" - } - }, - { - "name": "status", - "in": "query", - "description": "Filter segments by their indexing status.", - "schema": { - "type": "string", - "example": "completed" - } + }, + "description": "Document ID." }, { "name": "page", "in": "query", - "description": "Page number for pagination.", "schema": { "type": "integer", "default": 1 - } + }, + "description": "Page number to retrieve." }, { "name": "limit", "in": "query", - "description": "Number of items to return per page.", "schema": { "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } + "default": 20 + }, + "description": "Number of items per page. Server caps at `100`." + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "Filter chunks by indexing status, e.g. `completed`, `indexing`, `error`." + }, + { + "name": "keyword", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Search keyword." } ], "responses": { "200": { - "description": "Paginated list of segments.", + "description": "List of chunks.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentPaginatedResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "List of chunks.", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode used by this document." + }, + "total": { + "type": "integer", + "description": "Total number of matching chunks." + }, + "has_more": { + "type": "boolean", + "description": "Whether more items exist on the next page." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "page": { + "type": "integer", + "description": "Current page number." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model", + "total": 1, + "has_more": false, + "limit": 20, + "page": 1 + } + } } } } @@ -894,48 +3052,98 @@ "tags": [ "Chunks" ], - "summary": "Get a Chunk Details in a Document", - "description": "Retrieves the details of a specific chunk (segment) within a document.", + "summary": "Get Chunk", + "description": "Retrieve detailed information about a specific chunk, including its content, keywords, and indexing status.", "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "The ID of the segment.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "responses": { "200": { - "description": "Detailed information about the segment.", + "description": "Chunk details.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode used by this document." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } @@ -946,39 +3154,39 @@ "tags": [ "Chunks" ], - "summary": "Update a Chunk in a Document", - "description": "Updates the content, keywords, or status of a specific chunk (segment).", + "summary": "Update Chunk", + "description": "Update a chunk's content, keywords, or answer. Re-triggers indexing for the modified chunk.", "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "The ID of the segment to update.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "requestBody": { @@ -986,18 +3194,115 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateSegmentRequest" + "type": "object", + "required": [ + "segment" + ], + "properties": { + "segment": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "Chunk text content." + }, + "answer": { + "type": "string", + "description": "Answer content for QA mode." + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Keywords for the chunk." + }, + "enabled": { + "type": "boolean", + "description": "Whether the chunk is enabled." + }, + "regenerate_child_chunks": { + "type": "boolean", + "default": false, + "description": "Whether to regenerate child chunks." + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Attachment file IDs." + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary content for summary index." + } + }, + "description": "Chunk data to update." + } + } } } } }, "responses": { "200": { - "description": "Updated segment details.", + "description": "Chunk updated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode used by this document." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } @@ -1008,118 +3313,44 @@ "tags": [ "Chunks" ], - "summary": "Delete a Chunk in a Document", - "description": "Deletes a specific chunk (segment) from a document.", + "summary": "Delete Chunk", + "description": "Permanently delete a chunk from the document.", "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "The ID of the segment to delete.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "responses": { "204": { - "description": "Successfully deleted the segment." - } - } - } - }, - "/datasets/{dataset_id}/retrieve": { - "post": { - "tags": [ - "Datasets" - ], - "summary": "Retrieve Chunks from a Knowledge Base / Test Retrieval", - "description": "Performs a search query against a knowledge base to retrieve the most relevant chunks (segments). This endpoint can be used for both production retrieval and test retrieval.", - "operationId": "retrieveSegments", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "The ID of the knowledge base to retrieve from.", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RetrieveRequest" - } - } - } - }, - "responses": { - "200": { - "description": "List of retrieved segments matching the query.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RetrieveResponse" - } - } - } - } - } - } - }, - "/workspaces/current/models/model-types/text-embedding": { - "get": { - "tags": [ - "Models" - ], - "summary": "Get available embedding models", - "description": "Fetches a list of all available text embedding models that can be used for creating and querying knowledge bases.", - "operationId": "getAvailableEmbeddingModels", - "responses": { - "200": { - "description": "A list of available embedding models grouped by provider.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ModelProvider" - } - } - } - } - } - } + "description": "Success." } } } @@ -1130,38 +3361,38 @@ "Chunks" ], "summary": "Create Child Chunk", - "description": "Creates a new child chunk under a parent segment in a document using the hierarchical mode.", + "description": "Create a child chunk under a parent chunk. Only available for documents using the `hierarchical_model` chunking mode.", "operationId": "createChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "requestBody": { @@ -1169,18 +3400,66 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateChildChunkRequest" + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "Child chunk text content." + } + } } } } }, "responses": { "200": { - "description": "Successfully created child chunk.", + "description": "Child chunk created successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : Create child chunk index failed.", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } + } } } } @@ -1191,75 +3470,124 @@ "tags": [ "Chunks" ], - "summary": "Get Child Chunks", - "description": "Retrieves a list of child chunks for a specific parent segment.", + "summary": "List Child Chunks", + "description": "Returns a paginated list of child chunks under a specific parent chunk.", "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" - } - }, - { - "name": "keyword", - "in": "query", - "description": "Search keyword to filter child chunks.", - "schema": { - "type": "string" - } + }, + "description": "Chunk ID." }, { "name": "page", "in": "query", - "description": "Page number for pagination.", "schema": { "type": "integer", - "default": 1 - } + "default": 1, + "minimum": 1 + }, + "description": "Page number to retrieve." }, { "name": "limit", "in": "query", - "description": "Number of items to return per page.", "schema": { "type": "integer", "default": 20, - "maximum": 100 - } + "minimum": 1 + }, + "description": "Number of items per page. Server caps at `100`." + }, + { + "name": "keyword", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Search keyword." } ], "responses": { "200": { - "description": "A paginated list of child chunks.", + "description": "List of child chunks.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "List of child chunks.", + "items": { + "$ref": "#/components/schemas/ChildChunk" + } + }, + "total": { + "type": "integer", + "description": "Total number of child chunks." + }, + "total_pages": { + "type": "integer", + "description": "Total number of pages." + }, + "page": { + "type": "integer", + "description": "Current page number." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + ], + "total": 1, + "total_pages": 1, + "page": 1, + "limit": 20 + } + } } } } @@ -1273,48 +3601,48 @@ "Chunks" ], "summary": "Update Child Chunk", - "description": "Updates the content of a specific child chunk.", + "description": "Update the content of an existing child chunk.", "operationId": "updateChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." }, { "name": "child_chunk_id", "in": "path", "required": true, - "description": "The ID of the child chunk to update.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Child chunk ID." } ], "requestBody": { @@ -1322,18 +3650,66 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateChildChunkRequest" + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "Child chunk text content." + } + } } } } }, "responses": { "200": { - "description": "Successfully updated child chunk.", + "description": "Child chunk updated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : Update child chunk index failed.", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } + } } } } @@ -1345,77 +3721,138 @@ "Chunks" ], "summary": "Delete Child Chunk", - "description": "Deletes a specific child chunk.", + "description": "Permanently delete a child chunk from its parent chunk.", "operationId": "deleteChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." }, { "name": "child_chunk_id", "in": "path", "required": true, - "description": "The ID of the child chunk to delete.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Child chunk ID." } ], "responses": { "204": { - "description": "Successfully deleted the child chunk." + "description": "Success." + }, + "400": { + "description": "`invalid_param` : Delete child chunk index failed.", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Delete child chunk index failed: {error details}" + } + } + } + } + } } } } }, - "/datasets/tags": { + "/datasets/{dataset_id}/retrieve": { "post": { "tags": [ - "Metadata & Tags" + "Knowledge Bases" + ], + "summary": "Retrieve Chunks from a Knowledge Base / Test Retrieval", + "description": "Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used for both production retrieval and test retrieval.", + "operationId": "retrieveSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } ], - "summary": "Create New Knowledge Base Type Tag", - "description": "Creates a new tag that can be used to categorize knowledge bases.", - "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": ["name"], + "required": [ + "query" + ], "properties": { - "name": { + "query": { "type": "string", - "description": "The name of the new tag.", - "maxLength": 50 + "maxLength": 250, + "description": "Search query text." + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + }, + "external_retrieval_model": { + "type": "object", + "description": "Retrieval settings for external knowledge bases.", + "properties": { + "top_k": { + "type": "integer", + "description": "Maximum number of results to return." + }, + "score_threshold": { + "type": "number", + "description": "Minimum relevance score threshold for filtering results." + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + } + } + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "List of attachment IDs to include in the retrieval context." } } } @@ -1424,11 +3861,470 @@ }, "responses": { "200": { - "description": "Successfully created tag.", + "description": "Retrieval results.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "query": { + "type": "object", + "description": "The original query object.", + "properties": { + "content": { + "type": "string", + "description": "The query text." + } + } + }, + "records": { + "type": "array", + "description": "List of matched retrieval records.", + "items": { + "type": "object", + "properties": { + "segment": { + "type": "object", + "description": "Matched chunk from the knowledge base.", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the chunk." + }, + "position": { + "type": "integer", + "description": "Position of the chunk within the document." + }, + "document_id": { + "type": "string", + "description": "ID of the document this chunk belongs to." + }, + "content": { + "type": "string", + "description": "Text content of the chunk." + }, + "sign_content": { + "type": "string", + "description": "Signed content hash for integrity verification." + }, + "answer": { + "type": "string", + "description": "Answer content, used in Q&A mode documents." + }, + "word_count": { + "type": "integer", + "description": "Word count of the chunk content." + }, + "tokens": { + "type": "integer", + "description": "Token count of the chunk content." + }, + "keywords": { + "type": "array", + "description": "Keywords associated with this chunk for keyword-based retrieval.", + "items": { + "type": "string" + } + }, + "index_node_id": { + "type": "string", + "description": "ID of the index node in the vector store." + }, + "index_node_hash": { + "type": "string", + "description": "Hash of the indexed content, used to detect changes." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this chunk has been matched in retrieval queries." + }, + "enabled": { + "type": "boolean", + "description": "Whether the chunk is enabled for retrieval." + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when the chunk was disabled. `null` if enabled." + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "ID of the user who disabled the chunk. `null` if enabled." + }, + "status": { + "type": "string", + "description": "Indexing status of the chunk." + }, + "created_by": { + "type": "string", + "description": "ID of the user who created the chunk." + }, + "created_at": { + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." + }, + "indexing_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing started. `null` if not yet started." + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing completed. `null` if not yet completed." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if indexing failed. `null` when no error." + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing was stopped. `null` if not stopped." + }, + "document": { + "type": "object", + "description": "Parent document information for the matched chunk.", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the document." + }, + "data_source_type": { + "type": "string", + "description": "How the document was created." + }, + "name": { + "type": "string", + "description": "Document name." + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "Document type classification. `null` if not set." + }, + "doc_metadata": { + "type": "object", + "nullable": true, + "description": "Metadata values for the document. `null` if no metadata is configured." + } + } + } + } + }, + "child_chunks": { + "type": "array", + "description": "Matched child chunks within the chunk, if using hierarchical indexing.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the child chunk." + }, + "content": { + "type": "string", + "description": "Text content of the child chunk." + }, + "position": { + "type": "integer", + "description": "Position of the child chunk within the parent chunk." + }, + "score": { + "type": "number", + "description": "Relevance score of the child chunk." + } + } + } + }, + "score": { + "type": "number", + "description": "Relevance score." + }, + "tsne_position": { + "type": "object", + "nullable": true, + "description": "t-SNE visualization position." + }, + "files": { + "type": "array", + "description": "Files attached to this chunk.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Attachment file identifier." + }, + "name": { + "type": "string", + "description": "Original file name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "description": "File extension." + }, + "mime_type": { + "type": "string", + "description": "MIME type of the file." + }, + "source_url": { + "type": "string", + "description": "URL to access the attachment." + } + } + } + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary content if retrieved via summary index." + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "query": { + "content": "What is Dify?" + }, + "records": [ + { + "segment": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 1, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "data_source_type": "upload_file", + "name": "guide.txt", + "doc_type": null, + "doc_metadata": null + } + }, + "child_chunks": [], + "score": 0.92, + "tsne_position": null, + "files": [], + "summary": null + } + ] + } + } + } + } + } + }, + "400": { + "description": "- `dataset_not_initialized` : The dataset is still being initialized or indexing. Please wait a moment.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "dataset_not_initialized": { + "summary": "dataset_not_initialized", + "value": { + "status": 400, + "code": "dataset_not_initialized", + "message": "The dataset is still being initialized or indexing. Please wait a moment." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Invalid parameter value." + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Insufficient permissions.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Knowledge base not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : An internal error occurred during retrieval.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "An internal error occurred." + } + } + } + } + } + } + } + } + }, + "/datasets/tags": { + "post": { + "tags": [ + "Tags" + ], + "summary": "Create Knowledge Tag", + "description": "Create a new tag for organizing knowledge bases.", + "operationId": "createKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "Tag name." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Tag created successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Tag identifier." + }, + "name": { + "type": "string", + "description": "Tag display name." + }, + "type": { + "type": "string", + "description": "Tag type. Always `knowledge` for knowledge base tags." + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "Number of knowledge bases bound to this tag." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } } } } @@ -1437,20 +4333,52 @@ }, "get": { "tags": [ - "Metadata & Tags" + "Tags" ], - "summary": "Get Knowledge Base Type Tags", - "description": "Retrieves a list of all available knowledge base tags.", + "summary": "List Knowledge Tags", + "description": "Returns the list of all knowledge base tags in the workspace.", "operationId": "getKnowledgeTags", "responses": { "200": { - "description": "A list of tags.", + "description": "List of tags.", "content": { "application/json": { "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Tag identifier." + }, + "name": { + "type": "string", + "description": "Tag display name." + }, + "type": { + "type": "string", + "description": "Tag type. Always `knowledge` for knowledge base tags." + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "Number of knowledge bases bound to this tag." + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + ] } } } @@ -1460,10 +4388,10 @@ }, "patch": { "tags": [ - "Metadata & Tags" + "Tags" ], - "summary": "Modify Knowledge Base Type Tag Name", - "description": "Updates the name of an existing tag.", + "summary": "Update Knowledge Tag", + "description": "Rename an existing knowledge base tag.", "operationId": "updateKnowledgeTag", "requestBody": { "required": true, @@ -1471,17 +4399,20 @@ "application/json": { "schema": { "type": "object", - "required": ["tag_id", "name"], + "required": [ + "tag_id", + "name" + ], "properties": { "tag_id": { "type": "string", - "description": "The ID of the tag to modify.", - "format": "uuid" + "description": "Tag ID to update." }, "name": { "type": "string", - "description": "The new name for the tag.", - "maxLength": 50 + "minLength": 1, + "maxLength": 50, + "description": "New tag name." } } } @@ -1490,11 +4421,41 @@ }, "responses": { "200": { - "description": "Successfully updated tag.", + "description": "Tag updated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Tag identifier." + }, + "name": { + "type": "string", + "description": "Tag display name." + }, + "type": { + "type": "string", + "description": "Tag type. Always `knowledge` for knowledge base tags." + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "Number of knowledge bases bound to this tag." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } } } } @@ -1503,10 +4464,10 @@ }, "delete": { "tags": [ - "Metadata & Tags" + "Tags" ], - "summary": "Delete Knowledge Base Type Tag", - "description": "Deletes a tag. The tag must not be bound to any knowledge bases.", + "summary": "Delete Knowledge Tag", + "description": "Permanently delete a knowledge base tag. Does not delete the knowledge bases that were tagged.", "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, @@ -1514,12 +4475,13 @@ "application/json": { "schema": { "type": "object", - "required": ["tag_id"], + "required": [ + "tag_id" + ], "properties": { "tag_id": { "type": "string", - "description": "The ID of the tag to delete.", - "format": "uuid" + "description": "Tag ID to delete." } } } @@ -1527,8 +4489,8 @@ } }, "responses": { - "200": { - "$ref": "#/components/responses/Success" + "204": { + "description": "Success." } } } @@ -1536,10 +4498,10 @@ "/datasets/tags/binding": { "post": { "tags": [ - "Metadata & Tags" + "Tags" ], - "summary": "Bind Dataset to Knowledge Base Type Tag", - "description": "Binds one or more tags to a specific knowledge base.", + "summary": "Create Tag Binding", + "description": "Bind one or more tags to a knowledge base. A knowledge base can have multiple tags.", "operationId": "bindTagsToDataset", "requestBody": { "required": true, @@ -1547,20 +4509,22 @@ "application/json": { "schema": { "type": "object", - "required": ["target_id", "tag_ids"], + "required": [ + "tag_ids", + "target_id" + ], "properties": { - "target_id": { - "type": "string", - "description": "The ID of the dataset to bind tags to.", - "format": "uuid" - }, "tag_ids": { "type": "array", - "description": "A list of tag IDs to bind.", "items": { - "type": "string", - "format": "uuid" - } + "type": "string" + }, + "minItems": 1, + "description": "Tag IDs to bind." + }, + "target_id": { + "type": "string", + "description": "Knowledge base ID." } } } @@ -1568,8 +4532,8 @@ } }, "responses": { - "200": { - "$ref": "#/components/responses/Success" + "204": { + "description": "Success." } } } @@ -1577,10 +4541,10 @@ "/datasets/tags/unbinding": { "post": { "tags": [ - "Metadata & Tags" + "Tags" ], - "summary": "Unbind Dataset and Knowledge Base Type Tag", - "description": "Unbinds a specific tag from a knowledge base.", + "summary": "Delete Tag Binding", + "description": "Remove a tag binding from a knowledge base.", "operationId": "unbindTagFromDataset", "requestBody": { "required": true, @@ -1588,17 +4552,311 @@ "application/json": { "schema": { "type": "object", - "required": ["target_id", "tag_id"], + "required": [ + "tag_id", + "target_id" + ], "properties": { - "target_id": { - "type": "string", - "description": "The ID of the dataset.", - "format": "uuid" - }, "tag_id": { "type": "string", - "description": "The ID of the tag to unbind.", - "format": "uuid" + "description": "Tag ID to unbind." + }, + "target_id": { + "type": "string", + "description": "Knowledge base ID." + } + } + } + } + } + }, + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/{dataset_id}/tags": { + "get": { + "tags": [ + "Tags" + ], + "summary": "Get Knowledge Base Tags", + "description": "Returns the list of tags bound to a specific knowledge base.", + "operationId": "queryDatasetTags", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "responses": { + "200": { + "description": "Tags bound to the knowledge base.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "List of tags bound to this knowledge base.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Tag identifier." + }, + "name": { + "type": "string", + "description": "Tag display name." + } + } + } + }, + "total": { + "type": "integer", + "description": "Total number of tags bound to this knowledge base." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs" + } + ], + "total": 1 + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata": { + "post": { + "tags": [ + "Metadata" + ], + "summary": "Create Metadata Field", + "description": "Create a custom metadata field for the knowledge base. Metadata fields can be used to annotate documents with structured information.", + "operationId": "createMetadataField", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "string", + "number", + "time" + ], + "description": "`string` for text values, `number` for numeric values, `time` for date/time values." + }, + "name": { + "type": "string", + "description": "Metadata field name." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Metadata field created successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field type." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "get": { + "tags": [ + "Metadata" + ], + "summary": "List Metadata Fields", + "description": "Returns the list of all metadata fields (both custom and built-in) for the knowledge base, along with the count of documents using each field.", + "operationId": "listMetadataFields", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "responses": { + "200": { + "description": "Metadata fields for the knowledge base.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "doc_metadata": { + "type": "array", + "description": "List of metadata field definitions.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field type." + }, + "count": { + "type": "integer", + "description": "Number of documents using this metadata field." + } + } + } + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "Whether built-in metadata fields are enabled for this knowledge base." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "doc_metadata": [ + { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string", + "count": 3 + } + ], + "built_in_field_enabled": true + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/{metadata_id}": { + "patch": { + "tags": [ + "Metadata" + ], + "summary": "Update Metadata Field", + "description": "Rename a custom metadata field.", + "operationId": "updateMetadataField", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Metadata field ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "New metadata field name." } } } @@ -1607,34 +4865,358 @@ }, "responses": { "200": { - "$ref": "#/components/responses/Success" + "description": "Metadata field updated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field type." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } } } - } - }, - "/datasets/{dataset_id}/tags": { - "get": { + }, + "delete": { "tags": [ - "Metadata & Tags" + "Metadata" ], - "summary": "Query Tags Bound to a Dataset", - "description": "Retrieves all tags that are currently bound to a specific dataset.", - "operationId": "queryDatasetTags", + "summary": "Delete Metadata Field", + "description": "Permanently delete a custom metadata field. Documents using this field will lose their metadata values for it.", + "operationId": "deleteMetadataField", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the dataset.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." + }, + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Metadata field ID." + } + ], + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in": { + "get": { + "tags": [ + "Metadata" + ], + "summary": "Get Built-in Metadata Fields", + "description": "Returns the list of built-in metadata fields provided by the system (e.g., document type, source URL).", + "operationId": "getBuiltInMetadataFields", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." } ], "responses": { "200": { - "description": "A list of tags bound to the dataset.", + "description": "Built-in metadata fields.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "fields": { + "type": "array", + "description": "List of system-provided metadata fields.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Built-in field identifier. `document_name` for the document title, `uploader` for the creator, `upload_date` for creation time, `last_update_date` for last modification time, `source` for the document origin." + }, + "type": { + "type": "string", + "description": "Field data type. `string` for text values, `time` for date/time values." + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "fields": [ + { + "name": "document_name", + "type": "string" + }, + { + "name": "uploader", + "type": "string" + }, + { + "name": "upload_date", + "type": "time" + }, + { + "name": "last_update_date", + "type": "time" + }, + { + "name": "source", + "type": "string" + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in/{action}": { + "post": { + "tags": [ + "Metadata" + ], + "summary": "Update Built-in Metadata Field", + "description": "Enable or disable built-in metadata fields for the knowledge base.", + "operationId": "toggleBuiltInMetadataField", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + }, + "description": "`enable` to activate built-in metadata fields, `disable` to deactivate them." + } + ], + "responses": { + "200": { + "description": "Built-in metadata field toggled successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Operation result." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/metadata": { + "post": { + "tags": [ + "Metadata" + ], + "summary": "Update Document Metadata in Batch", + "description": "Update metadata values for multiple documents at once. Each document in the request receives the specified metadata key-value pairs.", + "operationId": "batchUpdateDocumentMetadata", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "operation_data" + ], + "properties": { + "operation_data": { + "type": "array", + "items": { + "type": "object", + "required": [ + "document_id", + "metadata_list" + ], + "properties": { + "document_id": { + "type": "string", + "description": "ID of the document whose metadata to update." + }, + "metadata_list": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { + "type": "string", + "description": "Metadata field ID." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "value": { + "description": "Metadata value. Can be a string, number, or `null`." + } + } + } + }, + "partial_update": { + "type": "boolean", + "default": false, + "description": "Whether to partially update metadata, keeping existing values for unspecified fields." + } + } + }, + "description": "Array of document metadata update operations. Each entry maps a document ID to its metadata key-value pairs." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Document metadata updated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Operation result." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/workspaces/current/models/model-types/{model_type}": { + "get": { + "tags": [ + "Models" + ], + "summary": "Get Available Models", + "description": "Retrieve the list of available models by type. Primarily used to query `text-embedding` and `rerank` models for knowledge base configuration.", + "operationId": "getAvailableModels", + "parameters": [ + { + "name": "model_type", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "text-embedding", + "rerank", + "llm", + "tts", + "speech2text", + "moderation" + ] + }, + "description": "Type of model to retrieve. For knowledge base configuration, use `text-embedding` for embedding models or `rerank` for reranking models." + } + ], + "responses": { + "200": { + "description": "Available models for the specified type.", "content": { "application/json": { "schema": { @@ -1642,16 +5224,656 @@ "properties": { "data": { "type": "array", + "description": "List of model providers with their available models.", "items": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" } + "provider": { + "type": "string", + "description": "Model provider identifier, e.g. `openai`, `cohere`." + }, + "label": { + "type": "object", + "description": "Localized display name of the provider.", + "properties": { + "en_US": { + "type": "string", + "description": "English display name." + }, + "zh_Hans": { + "type": "string", + "description": "Chinese display name." + } + } + }, + "icon_small": { + "type": "object", + "description": "URL of the provider's small icon.", + "properties": { + "en_US": { + "type": "string", + "description": "Small icon URL." + } + } + }, + "icon_large": { + "type": "object", + "description": "URL of the provider's large icon.", + "properties": { + "en_US": { + "type": "string", + "description": "Large icon URL." + } + } + }, + "status": { + "type": "string", + "description": "Provider status. `active` when credentials are configured and valid." + }, + "models": { + "type": "array", + "description": "List of available models from this provider.", + "items": { + "type": "object", + "properties": { + "model": { + "type": "string", + "description": "Model identifier. Use this as the `embedding_model` value when creating or updating a knowledge base." + }, + "label": { + "type": "object", + "description": "Localized display name of the model.", + "properties": { + "en_US": { + "type": "string", + "description": "English model name." + }, + "zh_Hans": { + "type": "string", + "description": "Chinese model name." + } + } + }, + "model_type": { + "type": "string", + "description": "Type of the model, matching the `model_type` path parameter." + }, + "features": { + "type": "array", + "nullable": true, + "description": "Supported features of the model, `null` if none.", + "items": { + "type": "string" + } + }, + "fetch_from": { + "type": "string", + "description": "Where the model definition comes from. `predefined-model` for built-in models, `customizable-model` for user-configured models." + }, + "model_properties": { + "type": "object", + "description": "Model-specific properties such as `context_size`." + }, + "status": { + "type": "string", + "description": "Model availability status. `active` when ready to use." + } + } + } + } } } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "provider": "openai", + "label": { + "en_US": "OpenAI", + "zh_Hans": "OpenAI" + }, + "icon_small": { + "en_US": "https://example.com/openai-small.svg" + }, + "icon_large": { + "en_US": "https://example.com/openai-large.svg" + }, + "status": "active", + "models": [ + { + "model": "text-embedding-3-small", + "label": { + "en_US": "text-embedding-3-small", + "zh_Hans": "text-embedding-3-small" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8191 + }, + "status": "active" + } + ] + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/pipeline/file-upload": { + "post": { + "tags": [ + "Knowledge Pipeline" + ], + "summary": "Upload Pipeline File", + "description": "Upload a file for use in a knowledge pipeline. Accepts a single file via `multipart/form-data`.", + "operationId": "uploadPipelineFile", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "The file to upload." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "File uploaded successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the uploaded file." }, - "total": { - "type": "integer" + "name": { + "type": "string", + "description": "Original file name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "description": "File extension." + }, + "mime_type": { + "type": "string", + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "string", + "description": "Upload timestamp in ISO 8601 format." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "report.pdf", + "size": 524288, + "extension": "pdf", + "mime_type": "application/pdf", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": "2025-03-06T12:00:00" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : Please upload your file.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `too_many_files` : Only one file is allowed.", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : File size exceeded.", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/datasource-plugins": { + "get": { + "tags": [ + "Knowledge Pipeline" + ], + "summary": "List Datasource Plugins", + "description": "List all datasource plugins available for a knowledge pipeline. Returns published or draft plugins depending on the `is_published` query parameter.", + "operationId": "listDatasourcePlugins", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "is_published", + "in": "query", + "schema": { + "type": "boolean", + "default": true + }, + "description": "Whether to retrieve published or draft datasource plugins. `true` returns published plugins, `false` returns draft plugins." + } + ], + "responses": { + "200": { + "description": "List of datasource plugins.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the datasource plugin." + }, + "name": { + "type": "string", + "description": "Display name of the datasource plugin." + }, + "type": { + "type": "string", + "description": "Type of the datasource plugin." + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": [ + { + "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", + "name": "Web Scraper", + "type": "online_document" + } + ] + } + } + } + } + }, + "404": { + "description": "`not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": { + "post": { + "tags": [ + "Knowledge Pipeline" + ], + "summary": "Run Datasource Node", + "description": "Execute a single datasource node within the knowledge pipeline. Returns a streaming response with the node execution results.", + "operationId": "runDatasourceNode", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "node_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "ID of the datasource node to execute." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "is_published" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the datasource node." + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "Type of the datasource." + }, + "credential_id": { + "type": "string", + "nullable": true, + "description": "ID of the credential to use for authentication with the datasource." + }, + "is_published": { + "type": "boolean", + "description": "Whether to run the published or draft version of the node. `true` runs the published version, `false` runs the draft." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Streaming response with node execution events.", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "Server-Sent Events stream containing node execution progress and results." + } + } + } + }, + "404": { + "description": "`not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/run": { + "post": { + "tags": [ + "Knowledge Pipeline" + ], + "summary": "Run Pipeline", + "description": "Execute the full knowledge pipeline for a knowledge base. Supports both streaming and blocking response modes.", + "operationId": "runPipeline", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "datasource_info_list", + "start_node_id", + "is_published", + "response_mode" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the pipeline." + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "Type of the datasource." + }, + "datasource_info_list": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "List of datasource information objects for the pipeline to process." + }, + "start_node_id": { + "type": "string", + "description": "ID of the node to start pipeline execution from." + }, + "is_published": { + "type": "boolean", + "description": "Whether to run the published or draft version of the pipeline. `true` runs the published version, `false` runs the draft." + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "Response mode for the pipeline execution. `streaming` returns a Server-Sent Events stream, `blocking` waits and returns the complete result." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Pipeline execution result. Format depends on `response_mode`: streaming returns a `text/event-stream`, blocking returns a JSON object.", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "Server-Sent Events stream containing pipeline execution progress and results. Returned when `response_mode` is `streaming`." + } + }, + "application/json": { + "schema": { + "type": "object", + "description": "Complete pipeline execution result. Returned when `response_mode` is `blocking`.", + "additionalProperties": true + }, + "examples": { + "success": { + "summary": "Blocking Response Example", + "value": { + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "data": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "status": "succeeded", + "outputs": {}, + "created_at": 1741267200, + "finished_at": 1741267210 + } + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Forbidden.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "500": { + "description": "`pipeline_run_error` : Pipeline execution failed.", + "content": { + "application/json": { + "examples": { + "pipeline_run_error": { + "summary": "pipeline_run_error", + "value": { + "status": 500, + "code": "pipeline_run_error", + "message": "Pipeline execution failed: connection timeout" } } } @@ -1663,403 +5885,338 @@ } }, "components": { - "securitySchemes": { - "ApiKeyAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "API_KEY", - "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with 'Bearer '. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" - } - }, - "responses": { - "Success": { - "description": "Operation successful.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" - } - } - } - } - } - }, - "FileError": { - "description": "Bad request related to file upload. Could be `no_file_uploaded` or `too_many_files`.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "FileTooLarge": { - "description": "File size exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "UnsupportedFileType": { - "description": "File type not allowed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "DatasetNameDuplicate": { - "description": "The dataset name already exists.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - }, "schemas": { - "ErrorResponse": { + "Dataset": { "type": "object", - "properties": { - "code": { - "type": "string", - "description": "A machine-readable error code." - }, - "message": { - "type": "string", - "description": "A human-readable error message." - }, - "status": { - "type": "integer", - "description": "The HTTP status code." - } - }, - "example": { - "code": "no_file_uploaded", - "message": "Please upload your file.", - "status": 400 - } - }, - "RetrievalModel": { - "type": "object", - "properties": { - "search_method": { - "type": "string", - "description": "The search method to use for retrieval.", - "enum": [ - "hybrid_search", - "semantic_search", - "full_text_search", - "keyword_search" - ] - }, - "reranking_enable": { - "type": "boolean", - "description": "Whether to enable a rerank model to improve search results." - }, - "reranking_mode": { - "type": "string", - "description": "The reranking mode.", - "default": "reranking_model", - "enum": [ - "reranking_model", - "weighted_score" - ] - }, - "reranking_model": { - "type": "object", - "description": "Configuration for the rerank model.", - "properties": { - "reranking_provider_name": { - "type": "string", - "description": "The provider of the rerank model." - }, - "reranking_model_name": { - "type": "string", - "description": "The name of the rerank model." - } - }, - "nullable": true - }, - "top_k": { - "type": "integer", - "description": "The number of top matching results to return." - }, - "score_threshold_enabled": { - "type": "boolean", - "description": "Whether to apply a score threshold to filter results." - }, - "score_threshold": { - "type": "number", - "format": "float", - "description": "The minimum score for a result to be included.", - "nullable": true - }, - "weights": { - "type": "number", - "format": "float", - "description": "The weight of semantic search in a hybrid search mode.", - "nullable": true - } - } - }, - "SummaryIndexSetting": { - "type": "object", - "description": "Configuration for Summary Auto-Gen.", - "properties": { - "enable": { - "type": "boolean", - "description": "Whether to enable Summary Auto-Gen." - }, - "model_name": { - "type": "string", - "description": "Name of the model to use for generating summaries." - }, - "model_provider_name": { - "type": "string", - "description": "Provider of the summary model." - }, - "summary_prompt": { - "type": "string", - "description": "Prompt template for generating summaries." - } - }, - "required": [ - "enable" - ] - }, - "PreprocessingRule": { - "type": "object", - "description": "A rule for preprocessing document content.", "properties": { "id": { "type": "string", - "description": "The unique identifier for the preprocessing rule.", - "enum": [ - "remove_extra_spaces", - "remove_urls_emails" - ] + "description": "Unique identifier of the knowledge base." }, - "enabled": { + "name": { + "type": "string", + "description": "Display name of the knowledge base. Unique within the workspace." + }, + "description": { + "type": "string", + "description": "Optional text describing the purpose or contents of the knowledge base." + }, + "provider": { + "type": "string", + "description": "Provider type. `vendor` for internally managed, `external` for external knowledge base connections." + }, + "permission": { + "type": "string", + "description": "Controls who can access this knowledge base. Possible values: `only_me`, `all_team_members`, `partial_members`." + }, + "data_source_type": { + "type": "string", + "description": "Data source type of the documents, `null` if not yet configured." + }, + "indexing_technique": { + "type": "string", + "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." + }, + "app_count": { + "type": "integer", + "description": "Number of applications currently using this knowledge base." + }, + "document_count": { + "type": "integer", + "description": "Total number of documents in the knowledge base." + }, + "word_count": { + "type": "integer", + "description": "Total word count across all documents." + }, + "created_by": { + "type": "string", + "description": "ID of the user who created the knowledge base." + }, + "author_name": { + "type": "string", + "description": "Display name of the creator." + }, + "created_at": { + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." + }, + "updated_by": { + "type": "string", + "description": "ID of the user who last updated the knowledge base." + }, + "updated_at": { + "type": "number", + "description": "Last update timestamp (Unix epoch in seconds)." + }, + "embedding_model": { + "type": "string", + "description": "Name of the embedding model used for indexing." + }, + "embedding_model_provider": { + "type": "string", + "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "embedding_available": { "type": "boolean", - "description": "Whether this rule is enabled." - } - } - }, - "SegmentationRule": { - "type": "object", - "description": "Rules for segmenting document content into chunks.", - "properties": { - "separator": { - "type": "string", - "description": "The custom delimiter used to separate segments." + "description": "Whether the configured embedding model is currently available." }, - "max_tokens": { - "type": "integer", - "description": "The maximum number of tokens allowed in a single segment." - } - } - }, - "SubChunkSegmentationRule": { - "type": "object", - "description": "Rules for segmenting parent chunks into smaller child chunks (for hierarchical mode).", - "properties": { - "separator": { - "type": "string", - "description": "The delimiter for sub-chunking." - }, - "max_tokens": { - "type": "integer", - "description": "The maximum token length for a sub-chunk." - }, - "chunk_overlap": { - "type": "integer", - "description": "The number of overlapping tokens between adjacent sub-chunks." - } - } - }, - "ProcessRule": { - "type": "object", - "description": "A set of rules for processing a document, including cleaning and segmentation.", - "properties": { - "mode": { - "type": "string", - "description": "The processing mode: automatic, custom, or hierarchical.", - "enum": [ - "automatic", - "custom", - "hierarchical" - ] - }, - "rules": { + "retrieval_model_dict": { "type": "object", - "description": "The specific rules to apply, used when mode is 'custom' or 'hierarchical'.", + "description": "Retrieval configuration for the knowledge base.", "properties": { - "pre_processing_rules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PreprocessingRule" + "search_method": { + "type": "string", + "description": "Search method used for retrieval. `keyword_search` for keyword matching, `semantic_search` for embedding-based similarity, `full_text_search` for full-text indexing, `hybrid_search` for a combination of semantic and keyword approaches." + }, + "reranking_enable": { + "type": "boolean", + "description": "Whether reranking is enabled." + }, + "reranking_mode": { + "type": "string", + "nullable": true, + "description": "Reranking mode. `reranking_model` for model-based reranking, `weighted_score` for score-based weighting. `null` if reranking is disabled." + }, + "reranking_model": { + "type": "object", + "description": "Reranking model configuration.", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "Provider name of the reranking model." + }, + "reranking_model_name": { + "type": "string", + "description": "Name of the reranking model." + } } }, - "segmentation": { - "$ref": "#/components/schemas/SegmentationRule" + "weights": { + "type": "object", + "nullable": true, + "description": "Weight configuration for hybrid search.", + "properties": { + "weight_type": { + "type": "string", + "description": "Strategy for balancing semantic and keyword search weights." + }, + "vector_setting": { + "type": "object", + "description": "Semantic search weight settings.", + "properties": { + "vector_weight": { + "type": "number", + "description": "Weight assigned to semantic (vector) search results." + }, + "embedding_provider_name": { + "type": "string", + "description": "Provider of the embedding model used for vector search." + }, + "embedding_model_name": { + "type": "string", + "description": "Name of the embedding model used for vector search." + } + } + }, + "keyword_setting": { + "type": "object", + "description": "Keyword search weight settings.", + "properties": { + "keyword_weight": { + "type": "number", + "description": "Weight assigned to keyword search results." + } + } + } + } }, - "parent_mode": { - "type": "string", - "description": "Retrieval mode for parent chunks in hierarchical mode.", - "enum": [ - "full-doc", - "paragraph" - ] + "top_k": { + "type": "integer", + "description": "Maximum number of results to return." }, - "subchunk_segmentation": { - "$ref": "#/components/schemas/SubChunkSegmentationRule" + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + }, + "score_threshold": { + "type": "number", + "description": "Minimum relevance score for results. Only effective when `score_threshold_enabled` is `true`." } - }, - "nullable": true - } - } - }, - "CreateDocumentByTextRequest": { - "type": "object", - "required": [ - "name", - "text" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." + } }, - "text": { - "type": "string", - "description": "Full text content of the document." + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "Summary index configuration.", + "properties": { + "enable": { + "type": "boolean", + "description": "Whether summary indexing is enabled." + }, + "model_name": { + "type": "string", + "description": "Name of the model used for generating summaries." + }, + "model_provider_name": { + "type": "string", + "description": "Provider of the summary generation model." + }, + "summary_prompt": { + "type": "string", + "description": "Prompt template used for summary generation." + } + } }, - "indexing_technique": { - "type": "string", - "description": "Indexing technique for the document.", - "enum": [ - "high_quality", - "economy" - ] + "tags": { + "type": "array", + "description": "Tags associated with this knowledge base.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Tag identifier." + }, + "name": { + "type": "string", + "description": "Tag name." + }, + "type": { + "type": "string", + "description": "Tag type. Always `knowledge` for knowledge base tags." + } + } + } }, "doc_form": { "type": "string", - "description": "Format of the indexed content.", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] + "description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction." }, - "doc_language": { + "external_knowledge_info": { + "type": "object", + "nullable": true, + "description": "Connection details for external knowledge bases. Present when `provider` is `external`.", + "properties": { + "external_knowledge_id": { + "type": "string", + "description": "ID of the external knowledge base." + }, + "external_knowledge_api_id": { + "type": "string", + "description": "ID of the external knowledge API connection." + }, + "external_knowledge_api_name": { + "type": "string", + "description": "Display name of the external knowledge API." + }, + "external_knowledge_api_endpoint": { + "type": "string", + "description": "Endpoint URL of the external knowledge API." + } + } + }, + "external_retrieval_model": { + "type": "object", + "nullable": true, + "description": "Retrieval settings for external knowledge bases. `null` for internal knowledge bases.", + "properties": { + "top_k": { + "type": "integer", + "description": "Maximum number of results to return from the external knowledge base." + }, + "score_threshold": { + "type": "number", + "description": "Minimum relevance score threshold." + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + } + } + }, + "doc_metadata": { + "type": "array", + "description": "Metadata field definitions for the knowledge base.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field value type." + } + } + } + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "Whether built-in metadata fields (e.g., `document_name`, `uploader`) are enabled." + }, + "pipeline_id": { "type": "string", - "description": "Language of the document, important for Q&A mode.", - "example": "English" + "nullable": true, + "description": "Pipeline ID, if a custom processing pipeline is configured." }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { + "runtime_mode": { "type": "string", - "description": "Name of the embedding model to use." + "nullable": true, + "description": "Runtime processing mode." }, - "embedding_model_provider": { + "chunk_structure": { "type": "string", - "description": "Provider of the embedding model." + "nullable": true, + "description": "Chunk structure configuration." }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Configuration for Summary Auto-Gen." - } - } - }, - "CreateDocumentByFileRequestData": { - "type": "object", - "description": "Metadata and rules for creating a document from a file.", - "properties": { - "original_document_id": { - "type": "string", - "description": "ID of an existing document to re-upload or modify.", - "format": "uuid" + "icon_info": { + "type": "object", + "nullable": true, + "description": "Icon display configuration for the knowledge base.", + "properties": { + "icon_type": { + "type": "string", + "description": "Type of icon." + }, + "icon": { + "type": "string", + "description": "Icon identifier or emoji." + }, + "icon_background": { + "type": "string", + "description": "Background color for the icon." + }, + "icon_url": { + "type": "string", + "description": "URL of a custom icon image." + } + } }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] + "is_published": { + "type": "boolean", + "description": "Whether the knowledge base is published." }, - "doc_form": { - "type": "string", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] + "total_documents": { + "type": "integer", + "description": "Total number of documents." }, - "doc_language": { - "type": "string", - "example": "English" + "total_available_documents": { + "type": "integer", + "description": "Number of documents that are enabled and available." }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + "enable_api": { + "type": "boolean", + "description": "Whether API access is enabled for this knowledge base." }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { - "type": "string" - }, - "embedding_model_provider": { - "type": "string" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Configuration for Summary Auto-Gen." - } - } - }, - "UpdateDocumentByTextRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "New name for the document (optional)." - }, - "text": { - "type": "string", - "description": "New text content for the document (optional)." - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - } - } - }, - "UpdateDocumentByFileRequestData": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "New name for the document (optional)." - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + "is_multimodal": { + "type": "boolean", + "description": "Whether multimodal content processing is enabled." } } }, @@ -2068,944 +6225,432 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "description": "Unique identifier of the document." }, "position": { - "type": "integer" + "type": "integer", + "description": "Display position of the document in the list." }, "data_source_type": { - "type": "string" + "type": "string", + "description": "How the document was created. `upload_file` for file uploads, `notion_import` for Notion imports." }, "data_source_info": { "type": "object", - "nullable": true + "description": "Raw data source information, varies by `data_source_type`." + }, + "data_source_detail_dict": { + "type": "object", + "description": "Detailed data source information including file details." }, "dataset_process_rule_id": { "type": "string", - "format": "uuid", - "nullable": true + "description": "ID of the processing rule applied to this document." }, "name": { - "type": "string" + "type": "string", + "description": "Document name." }, "created_from": { - "type": "string" + "type": "string", + "description": "Origin of the document. `api` for API creation, `web` for UI creation." }, "created_by": { "type": "string", - "format": "uuid" + "description": "ID of the user who created the document." }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." }, "tokens": { - "type": "integer" + "type": "integer", + "description": "Total number of tokens in the document." }, "indexing_status": { - "type": "string" + "type": "string", + "description": "Current indexing status. `waiting` for queued, `parsing` while extracting content, `cleaning` while removing noise, `splitting` while chunking, `indexing` while building vectors, `completed` when ready, `error` if failed, `paused` if manually paused." }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "Error message if indexing failed. `null` when no error." }, "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Whether the document is enabled for retrieval." }, "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true + "type": "number", + "nullable": true, + "description": "Timestamp when the document was disabled. `null` if enabled." }, "disabled_by": { "type": "string", - "format": "uuid", - "nullable": true + "nullable": true, + "description": "ID of the user who disabled the document. `null` if enabled." }, "archived": { - "type": "boolean" + "type": "boolean", + "description": "Whether the document is archived." }, "display_status": { - "type": "string" + "type": "string", + "description": "User-facing display status derived from `indexing_status` and `enabled` state." }, "word_count": { - "type": "integer" + "type": "integer", + "description": "Total word count of the document." }, "hit_count": { - "type": "integer" + "type": "integer", + "description": "Number of times the document has been matched in retrieval queries." }, "doc_form": { - "type": "string" - } - } - }, - "DocumentCreationResponse": { - "type": "object", - "properties": { - "document": { - "$ref": "#/components/schemas/Document" - }, - "batch": { "type": "string", - "description": "A batch identifier for tracking indexing progress." - } - } - }, - "CreateDatasetRequest": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "Name of the knowledge base." + "description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction." }, - "description": { - "type": "string", - "description": "Description of the knowledge base (optional)." - }, - "indexing_technique": { - "type": "string", - "description": "The indexing technique to use.", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "description": "Access permissions for the knowledge base.", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "provider": { - "type": "string", - "description": "The provider of the knowledge base.", - "enum": [ - "vendor", - "external" - ] - }, - "external_knowledge_api_id": { - "type": "string", - "description": "ID of the external knowledge API (if provider is 'external')." - }, - "external_knowledge_id": { - "type": "string", - "description": "ID of the external knowledge (if provider is 'external')." - }, - "embedding_model": { - "type": "string", - "description": "Name of the embedding model." - }, - "embedding_model_provider": { - "type": "string", - "description": "Provider of the embedding model." - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Configuration for Summary Auto-Gen." - } - } - }, - "Dataset": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string", - "nullable": true - }, - "provider": { - "type": "string" - }, - "permission": { - "type": "string" - }, - "data_source_type": { - "type": "string", - "nullable": true - }, - "indexing_technique": { - "type": "string", - "nullable": true - }, - "app_count": { - "type": "integer" - }, - "document_count": { - "type": "integer" - }, - "word_count": { - "type": "integer" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - }, - "updated_by": { - "type": "string", - "format": "uuid" - }, - "updated_at": { - "type": "integer", - "format": "int64" - }, - "embedding_model": { - "type": "string", - "nullable": true - }, - "embedding_model_provider": { - "type": "string", - "nullable": true - }, - "embedding_available": { - "type": "boolean", - "nullable": true - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Summary Auto-Gen configurations for this dataset.", - "nullable": true - } - } - }, - "DatasetListResponse": { - "type": "object", - "properties": { - "data": { + "doc_metadata": { "type": "array", - "items": { - "$ref": "#/components/schemas/Dataset" - } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - }, - "DatasetDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Dataset" - }, - { - "type": "object", - "properties": { - "retrieval_model_dict": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "tags": { - "type": "array", - "items": { - "type": "object" - } - }, - "doc_form": { - "type": "string", - "nullable": true - } - } - } - ] - }, - "UpdateDatasetRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "New name for the knowledge base." - }, - "description": { - "type": "string", - "description": "New description for the knowledge base." - }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "embedding_model_provider": { - "type": "string" - }, - "embedding_model": { - "type": "string" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Configuration for Summary Auto-Gen." - }, - "partial_member_list": { - "type": "array", - "description": "List of members for 'partial_members' permission.", + "description": "Metadata values assigned to this document.", "items": { "type": "object", - "required": [ - "user_id" - ], "properties": { - "user_id": { + "id": { "type": "string", - "description": "User ID of the member." + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field value type." + }, + "value": { + "type": "string", + "description": "Metadata value for this document." } } } - } - } - }, - "IndexingStatus": { - "type": "object", - "properties": { - "id": { + }, + "summary_index_status": { "type": "string", - "format": "uuid" + "nullable": true, + "description": "Status of the summary index for this document. `null` if summary indexing is not configured." }, - "indexing_status": { - "type": "string" - }, - "processing_started_at": { - "type": "number", - "format": "float" - }, - "parsing_completed_at": { - "type": "number", - "format": "float" - }, - "cleaning_completed_at": { - "type": "number", - "format": "float" - }, - "splitting_completed_at": { - "type": "number", - "format": "float" - }, - "completed_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "paused_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "error": { - "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "completed_segments": { - "type": "integer" - }, - "total_segments": { - "type": "integer" + "need_summary": { + "type": "boolean", + "description": "Whether a summary needs to be generated for this document." } } }, - "DocumentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" - } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - }, - "DocumentDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Document" - }, - { - "type": "object", - "properties": { - "dataset_process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "document_process_rule": { - "allOf": [ - { - "$ref": "#/components/schemas/ProcessRule" - }, - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "dataset_id": { - "type": "string" - } - } - } - ] - }, - "indexing_latency": { - "type": "number", - "format": "float", - "nullable": true - }, - "segment_count": { - "type": "integer" - }, - "average_segment_length": { - "type": "integer" - }, - "doc_language": { - "type": "string", - "nullable": true - } - } - } - ] - }, "Segment": { "type": "object", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "Unique identifier of the chunk." }, "position": { - "type": "integer" + "type": "integer", + "description": "Position of the chunk within the document." }, "document_id": { "type": "string", - "format": "uuid" + "description": "ID of the document this chunk belongs to." }, "content": { - "type": "string" + "type": "string", + "description": "Text content of the chunk." + }, + "sign_content": { + "type": "string", + "description": "Signed content hash for integrity verification." }, "answer": { "type": "string", - "nullable": true + "description": "Answer content, used in Q&A mode documents." }, "word_count": { - "type": "integer" + "type": "integer", + "description": "Word count of the chunk content." }, "tokens": { - "type": "integer" + "type": "integer", + "description": "Token count of the chunk content." }, "keywords": { "type": "array", + "description": "Keywords associated with this chunk for keyword-based retrieval.", "items": { "type": "string" } }, "index_node_id": { - "type": "string" + "type": "string", + "description": "ID of the index node in the vector store." }, "index_node_hash": { - "type": "string" + "type": "string", + "description": "Hash of the indexed content, used to detect changes." }, "hit_count": { - "type": "integer" + "type": "integer", + "description": "Number of times this chunk has been matched in retrieval queries." }, "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Whether the chunk is enabled for retrieval." }, "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true + "type": "number", + "nullable": true, + "description": "Timestamp when the chunk was disabled. `null` if enabled." }, "disabled_by": { "type": "string", - "format": "uuid", - "nullable": true + "nullable": true, + "description": "ID of the user who disabled the chunk. `null` if enabled." }, "status": { - "type": "string" + "type": "string", + "description": "Current indexing status of the chunk, e.g. `completed`, `indexing`, `error`." }, "created_by": { "type": "string", - "format": "uuid" + "description": "ID of the user who created the chunk." }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." + }, + "updated_at": { + "type": "number", + "description": "Last update timestamp (Unix epoch in seconds)." + }, + "updated_by": { + "type": "string", + "description": "ID of the user who last updated the chunk." }, "indexing_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "Timestamp when indexing started. `null` if not yet started." }, "completed_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "Timestamp when indexing completed. `null` if not yet completed." }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "Error message if indexing failed. `null` when no error." }, "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true + "type": "number", + "nullable": true, + "description": "Timestamp when indexing was stopped. `null` if not stopped." + }, + "child_chunks": { + "type": "array", + "description": "Child chunks belonging to this chunk. Only present for hierarchical mode documents.", + "items": { + "$ref": "#/components/schemas/ChildChunk" + } + }, + "attachments": { + "type": "array", + "description": "Files attached to this chunk.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Attachment file identifier." + }, + "name": { + "type": "string", + "description": "Original file name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "description": "File extension." + }, + "mime_type": { + "type": "string", + "description": "MIME type of the file." + }, + "source_url": { + "type": "string", + "description": "URL to access the attachment." + } + } + } }, "summary": { "type": "string", - "nullable": true - } - } - }, - "CreateSegmentsRequest": { - "type": "object", - "properties": { - "segments": { - "type": "array", - "items": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "The text content of the chunk (or question in Q&A mode)." - }, - "answer": { - "type": "string", - "description": "The answer content, required if the document is in Q&A mode." - }, - "keywords": { - "type": "array", - "description": "Keywords associated with the chunk.", - "items": { - "type": "string" - } - } - } - } - } - } - }, - "SegmentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Segment" - } - }, - "doc_form": { - "type": "string" - } - } - }, - "SegmentPaginatedResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/SegmentListResponse" - }, - { - "type": "object", - "properties": { - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - } - ] - }, - "SegmentDetailResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Segment" - }, - "doc_form": { - "type": "string" - } - } - }, - "UpdateSegmentRequest": { - "type": "object", - "properties": { - "segment": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string" - }, - "answer": { - "type": "string" - }, - "keywords": { - "type": "array", - "items": { - "type": "string" - } - }, - "summary": { - "type": "string", - "nullable": true - }, - "enabled": { - "type": "boolean" - }, - "regenerate_child_chunks": { - "type": "boolean", - "description": "Whether to regenerate child chunks (hierarchical mode)." - } - } - } - } - }, - "RetrieveRequest": { - "type": "object", - "required": [ - "query" - ], - "properties": { - "query": { - "type": "string", - "description": "The search query string." - }, - "retrieval_model": { - "allOf": [ - { - "$ref": "#/components/schemas/RetrievalModel" - }, - { - "type": "object", - "properties": { - "metadata_filtering_conditions": { - "type": "object", - "description": "Conditions for filtering results based on metadata.", - "properties": { - "logical_operator": { - "type": "string", - "enum": [ - "and", - "or" - ] - }, - "conditions": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the metadata field." - }, - "comparison_operator": { - "type": "string", - "description": "The operator for comparison." - }, - "value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } - ], - "nullable": true, - "description": "The value to compare against." - } - } - } - } - } - } - } - } - ] - } - } - }, - "RetrievedSegment": { - "type": "object", - "properties": { - "segment": { - "allOf": [ - { - "$ref": "#/components/schemas/Segment" - }, - { - "type": "object", - "properties": { - "document": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "data_source_type": { - "type": "string" - }, - "name": { - "type": "string" - } - } - } - } - } - ] - }, - "score": { - "type": "number", - "format": "float" - } - } - }, - "RetrieveResponse": { - "type": "object", - "properties": { - "query": { - "type": "object", - "properties": { - "content": { - "type": "string" - } - } - }, - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RetrievedSegment" - } - } - } - }, - "Model": { - "type": "object", - "properties": { - "model": { - "type": "string" - }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "model_type": { - "type": "string" - }, - "features": { - "type": "array", - "items": {}, - "nullable": true - }, - "fetch_from": { - "type": "string" - }, - "model_properties": { - "type": "object", - "properties": { - "context_size": { - "type": "integer" - } - } - }, - "deprecated": { - "type": "boolean" - }, - "status": { - "type": "string" - }, - "load_balancing_enabled": { - "type": "boolean" - } - } - }, - "ModelProvider": { - "type": "object", - "properties": { - "provider": { - "type": "string" - }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "icon_small": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } - }, - "icon_large": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } - }, - "status": { - "type": "string" - }, - "models": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Model" - } + "nullable": true, + "description": "AI-generated summary of the chunk content. `null` if summary indexing is not enabled." } } }, "ChildChunk": { "type": "object", - "description": "Represents a child chunk in a hierarchical segmentation.", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "segment_id": { "type": "string", "format": "uuid" }, - "content": { "type": "string" }, - "word_count": { "type": "integer" }, - "tokens": { "type": "integer" }, - "index_node_id": { "type": "string" }, - "index_node_hash": { "type": "string" }, - "status": { "type": "string" }, - "created_by": { "type": "string", "format": "uuid" }, - "created_at": { "type": "integer", "format": "int64" }, - "indexing_at": { "type": "integer", "format": "int64" }, - "completed_at": { "type": "integer", "format": "int64" }, - "error": { "type": "string", "nullable": true }, - "stopped_at": { "type": "integer", "format": "int64", "nullable": true } - } - }, - "CreateChildChunkRequest": { - "type": "object", - "required": ["content"], "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the child chunk." + }, + "segment_id": { + "type": "string", + "description": "ID of the parent chunk this child chunk belongs to." + }, "content": { "type": "string", - "description": "The content of the child chunk." - } - } - }, - "UpdateChildChunkRequest": { - "type": "object", - "required": ["content"], - "properties": { - "content": { + "description": "Text content of the child chunk." + }, + "position": { + "type": "integer", + "description": "Position of the child chunk within the parent chunk." + }, + "word_count": { + "type": "integer", + "description": "Word count of the child chunk content." + }, + "type": { "type": "string", - "description": "The updated content for the child chunk." + "description": "How the child chunk was created. `automatic` for system-generated, `custom` for manually created." + }, + "created_at": { + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." + }, + "updated_at": { + "type": "number", + "description": "Last update timestamp (Unix epoch in seconds)." } } }, - "ChildChunkResponse": { + "RetrievalModel": { "type": "object", + "required": [ + "search_method", + "reranking_enable", + "top_k", + "score_threshold_enabled" + ], "properties": { - "data": { - "$ref": "#/components/schemas/ChildChunk" - } - } - }, - "ChildChunkListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ChildChunk" + "search_method": { + "type": "string", + "description": "Search method used for retrieval.", + "enum": [ + "keyword_search", + "semantic_search", + "full_text_search", + "hybrid_search" + ] + }, + "reranking_enable": { + "type": "boolean", + "description": "Whether reranking is enabled." + }, + "reranking_model": { + "type": "object", + "description": "Reranking model configuration.", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "Provider name of the reranking model." + }, + "reranking_model_name": { + "type": "string", + "description": "Name of the reranking model." + } } }, - "total": { "type": "integer" }, - "total_pages": { "type": "integer" }, - "page": { "type": "integer" }, - "limit": { "type": "integer" } - } - }, - "UploadFileResponse": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" }, - "size": { "type": "integer" }, - "extension": { "type": "string" }, - "url": { "type": "string", "format": "uri", "description": "Preview URL for the file." }, - "download_url": { "type": "string", "format": "uri", "description": "Download URL for the file." }, - "mime_type": { "type": "string" }, - "created_by": { "type": "string", "format": "uuid" }, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "Tag": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" }, - "type": { "type": "string", "example": "knowledge" }, - "binding_count": { "type": "integer" } + "reranking_mode": { + "type": "string", + "enum": [ + "reranking_model", + "weighted_score" + ], + "nullable": true, + "description": "Reranking mode. Required when `reranking_enable` is `true`." + }, + "top_k": { + "type": "integer", + "description": "Maximum number of results to return." + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + }, + "score_threshold": { + "type": "number", + "nullable": true, + "description": "Minimum relevance score for results. Only effective when `score_threshold_enabled` is `true`." + }, + "weights": { + "type": "object", + "nullable": true, + "description": "Weight configuration for hybrid search.", + "properties": { + "weight_type": { + "type": "string", + "description": "Strategy for balancing semantic and keyword search weights.", + "enum": [ + "semantic_first", + "keyword_first", + "customized" + ] + }, + "vector_setting": { + "type": "object", + "description": "Semantic search weight settings.", + "properties": { + "vector_weight": { + "type": "number", + "description": "Weight assigned to semantic (vector) search results." + }, + "embedding_provider_name": { + "type": "string", + "description": "Provider of the embedding model used for vector search." + }, + "embedding_model_name": { + "type": "string", + "description": "Name of the embedding model used for vector search." + } + } + }, + "keyword_setting": { + "type": "object", + "description": "Keyword search weight settings.", + "properties": { + "keyword_weight": { + "type": "number", + "description": "Weight assigned to keyword search results." + } + } + } + } + } } } + }, + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" + } } } } diff --git a/en/api-reference/openapi_workflow.json b/en/api-reference/openapi_workflow.json index 6306b7d1..756bf9a3 100644 --- a/en/api-reference/openapi_workflow.json +++ b/en/api-reference/openapi_workflow.json @@ -2,7 +2,7 @@ "openapi": "3.0.1", "info": { "title": "Workflow App API", - "description": "Workflow applications offers non-session support and is ideal for translation, article writing, summarization AI, and more.", + "description": "Workflow applications offer non-session support and are ideal for translation, article writing, summarization AI, and more.", "version": "1.0.0" }, "servers": [ @@ -25,10 +25,12 @@ "paths": { "/workflows/run": { "post": { - "summary": "Execute Workflow", - "description": "Execute workflow. Cannot be executed without a published workflow.", + "summary": "Run Workflow", + "description": "Execute a workflow. Cannot be executed without a published workflow.", "operationId": "executeWorkflow", - "tags": ["Workflow Execution"], + "tags": [ + "Workflows" + ], "requestBody": { "required": true, "content": { @@ -37,25 +39,35 @@ "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { - "basic_execution": { - "summary": "Basic workflow execution", + "streaming_example": { + "summary": "Request Example - Streaming mode", "value": { "inputs": { - "query": "Summarize this text: ..." + "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", "user": "user_workflow_123" } }, - "with_file_array_variable":{ - "summary": "Example with a file array input variable", + "blocking_example": { + "summary": "Request Example - Blocking mode", + "value": { + "inputs": { + "query": "Translate this to French: Hello world" + }, + "response_mode": "blocking", + "user": "user_workflow_456" + } + }, + "with_file_array_variable": { + "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", - "upload_file_id": "uploaded_file_id_abc" + "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", @@ -65,7 +77,7 @@ ] }, "response_mode": "blocking", - "user": "user_workflow_456" + "user": "user_workflow_789" } } } @@ -74,23 +86,357 @@ }, "responses": { "200": { - "description": "Successful workflow execution. Structure depends on `response_mode`.\n- `blocking`: `application/json` with `WorkflowCompletionResponse`.\n- `streaming`: `text/event-stream` with `ChunkWorkflowEvent` stream.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowCompletionResponse" + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "Response Example - Blocking mode", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Bonjour le monde" + }, + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630 + } + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "A stream of Server-Sent Events. See `ChunkWorkflowEvent` for structures." + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkWorkflowEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `workflow_finished` or `error` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." + }, + "examples": { + "streamingResponse": { + "summary": "Response Example - Streaming mode", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestWorkflow" }, - "500": { "$ref": "#/components/responses/InternalServerError" } + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal Server Error." + } + } + } + } + } + } + } + } + }, + "/workflows/{workflow_id}/run": { + "post": { + "summary": "Run Workflow by ID", + "description": "Execute a specific workflow version identified by its ID. Useful for running a particular published version of the workflow.", + "operationId": "runWorkflowById", + "tags": [ + "Workflows" + ], + "parameters": [ + { + "name": "workflow_id", + "in": "path", + "required": true, + "description": "Workflow ID of the specific version to execute. This value is returned in the `workflow_id` field of [Run Workflow](/api-reference/workflows/run-workflow) responses and [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowExecutionRequest" + }, + "examples": { + "example": { + "summary": "Request Example", + "value": { + "inputs": { + "query": "Summarize this article" + }, + "response_mode": "blocking", + "user": "user_workflow_123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "Response Example - Blocking mode", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Article summary here" + }, + "error": null, + "elapsed_time": 2.45, + "total_tokens": 280, + "total_steps": 4, + "created_at": 1705407629, + "finished_at": 1705407631 + } + } + } + } + }, + "text/event-stream": { + "schema": { + "type": "string", + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkWorkflowEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `workflow_finished` or `error` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." + } + } + } + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Required parameter missing or invalid.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Workflow is a draft and cannot be executed." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Workflow not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal Server Error." + } + } + } + } + } + } } } }, @@ -99,14 +445,18 @@ "summary": "Get Workflow Run Detail", "description": "Retrieve the current execution results of a workflow task based on the workflow execution ID.", "operationId": "getWorkflowRunDetail", - "tags": ["Workflow Execution"], + "tags": [ + "Workflows" + ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, - "description": "Workflow Run ID, can be obtained from workflow execution response or streaming events.", - "schema": { "type": "string", "format": "uuid" } + "description": "Workflow run ID, can be obtained from the workflow execution response or streaming events.", + "schema": { + "type": "string" + } } ], "responses": { @@ -114,27 +464,228 @@ "description": "Successfully retrieved workflow run details.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponse" } + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "Response Example", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } } } }, - "404": {"description": "Workflow run not found."} + "400": { + "description": "`not_workflow_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Workflow run not found.", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } + } + } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "List Workflow Logs", + "description": "Retrieve paginated workflow execution logs with filtering options.", + "operationId": "getWorkflowLogs", + "tags": [ + "Workflows" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "Keyword to search in logs.", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "Filter by execution status.", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "Page number for pagination.", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of items per page.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "Filter logs created before this ISO 8601 timestamp.", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "Filter logs created after this ISO 8601 timestamp.", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "Filter by end user session ID.", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "Filter by account ID.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved workflow logs.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "Response Example", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0, + "triggered_from": "app" + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_workflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } } } }, "/workflows/tasks/{task_id}/stop": { "post": { - "summary": "Stop Workflow Task Generation", - "description": "Stops a workflow task generation. Only supported in streaming mode.", + "summary": "Stop Workflow Task", + "description": "Stop a running workflow task. Only supported in `streaming` mode.", "operationId": "stopWorkflowTaskGeneration", - "tags": ["Workflow Execution"], + "tags": [ + "Workflows" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "Task ID from the streaming chunk.", - "schema": { "type": "string", "format": "uuid" } + "description": "Task ID, can be obtained from the streaming chunk return of the [Run Workflow](/api-reference/workflows/run-workflow) API.", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -143,35 +694,22 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { - "user": { "type": "string", "description": "User identifier." } + "user": { + "type": "string", + "description": "User identifier, must be consistent with the user passed in the [Run Workflow](/api-reference/workflows/run-workflow) request." + } } - } - } - } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } - } - } - }, - "/files/upload": { - "post": { - "summary": "File Upload for Workflow", - "description": "Upload a file for use in workflows. Supports any formats supported by your workflow. Uploaded files are for the current end-user only.", - "operationId": "uploadWorkflowFile", - "tags": ["Files"], - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { "type": "string", "format": "binary", "description": "The file to be uploaded." }, - "user": { "type": "string", "description": "User identifier." } + }, + "examples": { + "example": { + "summary": "Request Example", + "value": { + "user": "user_workflow_123" + } } } } @@ -179,34 +717,277 @@ }, "responses": { "200": { - "description": "File uploaded successfully.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } + "$ref": "#/components/responses/SuccessResult" }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `invalid_param` : Required parameter missing or invalid.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + } + } + } + }, + "/files/upload": { + "post": { + "operationId": "uploadWorkflowFile", + "tags": [ + "Files" + ], + "summary": "Upload File", + "description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", + "requestBody": { + "description": "File upload request. Requires multipart/form-data.", + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "The file to be uploaded. Supported types include images, documents, audio, and video." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer's rules, must be unique within the application." + } + } + } + } + } + }, + "responses": { "201": { - "description": "File created successfully (alternative success code).", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } + "description": "File uploaded successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } }, - "400": { "$ref": "#/components/responses/BadRequestFile" }, - "413": { "$ref": "#/components/responses/FileTooLarge" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFile" }, - "503": { "$ref": "#/components/responses/S3ErrorFile" }, - "500": { "$ref": "#/components/responses/InternalServerError" } + "400": { + "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : File size exceeded.", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { + "get": { + "operationId": "downloadWorkflowFile", + "tags": [ + "Files" + ], + "summary": "Download File", + "description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier, used for end-user context.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : Access to the requested file is denied.", + "content": { + "application/json": { + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : The requested file was not found.", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } } } }, "/end-users/{end_user_id}": { "get": { - "summary": "Get End User", - "description": "Retrieve an end user by ID.\n\nThis is useful when other APIs return an end-user ID (e.g. `created_by` from File Upload).", "operationId": "getEndUserWorkflow", - "tags": ["End Users"], + "tags": [ + "End Users" + ], + "summary": "Get End User Info", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).", "parameters": [ { "name": "end_user_id", "in": "path", "required": true, "description": "End user ID.", - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -214,322 +995,2855 @@ "description": "End user retrieved successfully.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetail" } + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "Response Example", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } + "404": { + "description": "`end_user_not_found` : End user not found.", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } } } }, - "/workflows/logs": { - "get": { - "summary": "Get Workflow Logs", - "description": "Returns workflow logs, with the first page returning the latest `{limit}` messages, i.e., in reverse order.", - "operationId": "getWorkflowLogs", - "tags": ["Workflow Execution"], - "parameters": [ - { "name": "keyword", "in": "query", "description": "Keyword to search.", "schema": { "type": "string" } }, - { "name": "status", "in": "query", "description": "Filter by status.", "schema": { "type": "string", "enum": ["succeeded", "failed", "stopped", "running"] } }, - { "name": "page", "in": "query", "description": "Current page.", "schema": { "type": "integer", "default": 1 } }, - { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer", "default": 20 } } - ], - "responses": { - "200": { - "description": "Successfully retrieved workflow logs.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponse" } } } - } + "/audio-to-text": { + "post": { + "operationId": "workflowAudioToText", + "tags": [ + "TTS" + ], + "summary": "Convert Audio to Text", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } } + } + }, + "responses": { + "200": { + "description": "Successfully converted audio to text.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "Response Example", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : Audio file size exceeded the limit.", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : Audio type is not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } } + } + }, + "/text-to-audio": { + "post": { + "operationId": "workflowTextToAudio", + "tags": [ + "TTS" + ], + "summary": "Convert Text to Audio", + "description": "Convert text to speech.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "Request Example", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } }, "/info": { "get": { - "summary": "Get Application Basic Information", "operationId": "getWorkflowAppInfo", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App Info", + "description": "Retrieve basic information about this application, including name, description, tags, and mode.", "responses": { - "200": { "description": "Basic application information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponse" } } } } + "200": { + "description": "Basic information of the application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "Response Example", + "value": { + "name": "My Workflow App", + "description": "A helpful customer service chatbot.", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "workflow", + "author_name": "Dify Team" + } + } + } + } + } + } } } }, "/parameters": { "get": { - "summary": "Get Application Parameters Information", "operationId": "getWorkflowAppParameters", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App Parameters", + "description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.", "responses": { - "200": { "description": "Application parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowAppParametersResponse" } } } } + "200": { + "description": "Application parameters information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "Response Example", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : App unavailable or misconfigured.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getWorkflowAppMeta", + "tags": [ + "Applications" + ], + "summary": "Get App Meta", + "description": "Retrieve metadata about this application, including tool icons and other configuration details.", + "responses": { + "200": { + "description": "Successfully retrieved application meta information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "Response Example", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } } } }, "/site": { "get": { - "summary": "Get Application WebApp Settings", "operationId": "getWorkflowWebAppSettings", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App WebApp Settings", + "description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.", "responses": { - "200": { "description": "WebApp settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWebAppSettingsResponse" } } } } + "200": { + "description": "WebApp settings of the application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "Response Example", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "A helpful customer service chatbot.", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Site not found for this application or the workspace has been archived.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API Key authentication." } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" + } }, "responses": { - "BadRequestWorkflow": { "description": "Bad Request for workflow operation. Possible error codes: invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, workflow_request_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "BadRequestFile": { "description": "Bad Request for file operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "FileTooLarge": { "description": "File is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "UnsupportedFileTypeFile": { "description": "Unsupported file type for upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "S3ErrorFile": { "description": "S3 storage error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "InternalServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "SuccessResult": { "description": "Operation successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "EndUserNotFound": { "description": "End user not found. Error code: `end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } + "SuccessResult": { + "description": "Operation successful.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "success" + ], + "description": "Operation result." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { "WorkflowExecutionRequest": { "type": "object", - "required": ["inputs", "response_mode", "user"], + "required": [ + "inputs", + "user" + ], "properties": { "inputs": { "type": "object", - "description": "Key/value pairs for workflow variables. Value for a file array type variable should be a list of InputFileObjectWorkflow.", + "description": "Key-value pairs for workflow input variables. Values for file-type variables should be arrays of file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", "additionalProperties": { "oneOf": [ - { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, - { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectWorkflow" } } + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "object" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + } + } ] - }, - "example": { "user_query": "Translate this for me.", "target_language": "French" } + } }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "description": "Response mode. Cloudflare timeout is 100s for blocking." }, - "user": { "type": "string", "description": "User identifier." } + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events. When omitted, defaults to blocking behavior." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer's rules, must be unique within the application. This identifier scopes data access — workflow runs and files are only visible when queried with the same `user` value." + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + }, + "nullable": true, + "description": "File list. Suitable when files need to be combined with text for input, available only when the model supports Vision capability. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`." + } } }, - "InputFileObjectWorkflow": { + "InputFileObject": { "type": "object", - "required": ["type", "transfer_method"], + "required": [ + "type", + "transfer_method" + ], "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "Type of file." }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "Transfer method, `remote_url` for image URL / `local_file` for file upload" }, - "url": { "type": "string", "format": "url", "description": "Image URL (when the transfer method is `remote_url`)" }, - "upload_file_id": { "type": "string", "description": "Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`)" } - }, - "anyOf": [ - { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "type": { + "type": "string", + "enum": [ + "document", + "image", + "audio", + "video", + "custom" + ], + "description": "File type." }, - { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file." + }, + "url": { + "type": "string", + "format": "url", + "description": "File URL (when `transfer_method` is `remote_url`)." + }, + "upload_file_id": { + "type": "string", + "description": "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (when `transfer_method` is `local_file`)." } - ] + } }, - "WorkflowCompletionResponse": { + "WorkflowBlockingResponse": { "type": "object", - "description": "Response for blocking mode workflow execution.", "properties": { - "workflow_run_id": { "type": "string", "format": "uuid" }, - "task_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/api-reference/workflows/stop-workflow-task) to cancel a running workflow. Only valid during execution." + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." + }, + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } } }, "ChunkWorkflowEvent": { "type": "object", - "required": ["event"], + "required": [ + "event" + ], "properties": { - "event": { "type": "string", "enum": ["workflow_started", "node_started", "text_chunk", "node_finished", "workflow_finished", "tts_message", "tts_message_end", "ping"] } + "event": { + "type": "string", + "description": "The type of streaming event.", + "enum": [ + "workflow_started", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "text_chunk", + "text_replace", + "workflow_finished", + "tts_message", + "tts_message_end", + "workflow_paused", + "agent_log", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "error", + "ping" + ] + } }, "discriminator": { "propertyName": "event", "mapping": { - "workflow_started": "#/components/schemas/StreamEventWfWorkflowStarted", - "node_started": "#/components/schemas/StreamEventWfNodeStarted", - "text_chunk": "#/components/schemas/StreamEventWfTextChunk", - "node_finished": "#/components/schemas/StreamEventWfNodeFinished", - "workflow_finished": "#/components/schemas/StreamEventWfWorkflowFinished", - "tts_message": "#/components/schemas/StreamEventWfTtsMessage", - "tts_message_end": "#/components/schemas/StreamEventWfTtsMessageEnd", - "ping": "#/components/schemas/StreamEventWfPing" + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "text_chunk": "#/components/schemas/StreamEventTextChunk", + "text_replace": "#/components/schemas/StreamEventTextReplace", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "tts_message": "#/components/schemas/StreamEventTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", + "error": "#/components/schemas/StreamEventError", + "ping": "#/components/schemas/StreamEventPing", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout" } } }, - "StreamEventBaseWf": { + "StreamEventBase": { "type": "object", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" } + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/api-reference/workflows/stop-workflow-task) to cancel a running workflow. Only valid during execution." + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." + } } }, - "StreamEventWfWorkflowStarted": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowStartedData" } } } ] + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for this workflow run." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run started." + }, + "reason": { + "type": "string", + "description": "Reason for the workflow start. `initial` for a new execution, `resumption` when resuming from a paused state." + } + } + } + } + } + ] }, - "WorkflowStartedData": { - "type": "object", "required": ["id", "workflow_id", "sequence_number", "created_at"], - "properties": { "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "sequence_number": { "type": "integer" }, "created_at": { "type": "integer", "format": "int64" } } + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type (e.g., `llm`, `code`, `template-transform`)." + }, + "title": { + "type": "string", + "description": "Display name of the node." + }, + "index": { + "type": "integer", + "description": "Execution sequence index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node, if any." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Input variables for this node." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the node execution started." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata for the node execution." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Parent iteration ID if this node runs inside an iteration." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Parent loop ID if this node runs inside a loop." + } + } + } + } + } + ] }, - "StreamEventWfNodeStarted": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeStartedData" } } } ] + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Display name of the node." + }, + "index": { + "type": "integer", + "description": "Execution sequence index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node, if any." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Input variables for this node." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Processing data generated during node execution." + }, + "process_data_truncated": { + "type": "boolean", + "description": "Whether the `process_data` was truncated." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Output data from the node." + }, + "outputs_truncated": { + "type": "boolean", + "description": "Whether the `outputs` data was truncated." + }, + "status": { + "type": "string", + "description": "Node execution status. `running` for in-progress, `succeeded` when completed, `failed` on error, `stopped` when manually halted, `exception` on unexpected failure." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the node failed." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Time elapsed in seconds." + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "description": "Execution metadata including token usage.", + "properties": { + "total_tokens": { + "type": "integer", + "nullable": true, + "description": "Total tokens consumed by this node." + }, + "total_price": { + "type": "number", + "format": "float", + "nullable": true, + "description": "Total cost for this node execution." + }, + "currency": { + "type": "string", + "nullable": true, + "description": "Currency of the cost (e.g., `USD`)." + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the node execution started." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the node execution finished." + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files generated by this node." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Parent iteration ID if this node runs inside an iteration." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Parent loop ID if this node runs inside a loop." + } + } + } + } + } + ] }, - "NodeStartedData": { - "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], - "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "format": "uuid" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true }, "inputs": { "type": "object", "additionalProperties": true }, "created_at": { "type": "integer", "format": "int64" } } + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Display name of the node." + }, + "index": { + "type": "integer", + "description": "Execution sequence index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node, if any." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Processing data generated during node execution." + }, + "process_data_truncated": { + "type": "boolean", + "description": "Whether the `process_data` was truncated." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "Whether the `outputs` data was truncated." + }, + "status": { + "type": "string", + "description": "Node execution status at the retry point." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message that triggered the retry." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Time elapsed in seconds." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "retry_index": { + "type": "integer", + "description": "Zero-based retry attempt index." + }, + "iteration_id": { + "type": "string", + "nullable": true + }, + "loop_id": { + "type": "string", + "nullable": true + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Metadata from the node execution." + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files produced by the node during execution." + } + } + } + } + } + ] }, - "StreamEventWfTextChunk": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/TextChunkData" } } } ] + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Iteration node ID." + }, + "node_type": { + "type": "string", + "description": "Node type (always `iteration`)." + }, + "title": { + "type": "string", + "description": "Display name of the iteration node." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the iteration." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Iteration metadata." + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] }, - "TextChunkData": { - "type": "object", "required": ["text", "from_variable_selector"], - "properties": { "text": { "type": "string" }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "description": "Text source path." } } + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "Current iteration index (zero-based)." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] }, - "StreamEventWfNodeFinished": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeFinishedData" } } } ] + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "Whether the `outputs` data was truncated." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Input variables for the iteration." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the iteration started." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Additional metadata for the iteration." + }, + "status": { + "type": "string", + "description": "Iteration completion status." + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "Execution metadata including token usage." + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "Number of iteration steps completed." + } + } + } + } + } + ] }, - "NodeFinishedData": { - "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "status", "created_at"], - "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "format": "uuid" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float", "nullable": true }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadata" , "nullable": true }, "created_at": { "type": "integer", "format": "int64" } } + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "metadata": { + "type": "object", + "additionalProperties": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] }, - "NodeExecutionMetadata": { - "type": "object", "properties": { "total_tokens": { "type": "integer", "nullable": true }, "total_price": { "type": "number", "format": "float", "nullable": true }, "currency": { "type": "string", "nullable": true, "example": "USD" } } + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "Current loop iteration index (zero-based)." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "pre_loop_output": { + "description": "Output from the previous loop iteration.", + "nullable": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] }, - "StreamEventWfWorkflowFinished": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } } ] + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "Whether the `outputs` data was truncated." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Input variables for the loop." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Additional metadata for the loop." + }, + "status": { + "type": "string", + "description": "Loop completion status." + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "Execution metadata including token usage." + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "Number of loop iterations completed." + } + } + } + } + } + ] + }, + "StreamEventTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The text content chunk." + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "Source path of the text variable in the workflow." + } + } + } + } + } + ] + }, + "StreamEventTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The replacement text content." + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } + } + } + ] + }, + "StreamEventTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when this audio chunk was generated." + } + } + } + ] + }, + "StreamEventTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "description": "Empty string. Signals the end of the audio stream." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the audio stream ended." + } + } + } + ] + }, + "StreamEventError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code of the error." + }, + "code": { + "type": "string", + "description": "Error code." + }, + "message": { + "type": "string", + "description": "Error message." + } + } + } + ] + }, + "StreamEventPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "type": "object", + "description": "Keep-alive ping event. No additional properties." + } + ] }, "WorkflowFinishedData": { - "type": "object", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], - "properties": { "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float", "nullable": true }, "total_tokens": { "type": "integer", "nullable": true }, "total_steps": { "type": "integer", "default": 0 }, "created_at": { "type": "integer", "format": "int64" }, "finished_at": { "type": "integer", "format": "int64" } } - }, - "StreamEventWfTtsMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "format": "byte" }, "message_id": {"type": "string", "format": "uuid"}, "created_at": {"type": "integer", "format":"int64"} } } - ] - }, - "StreamEventWfTtsMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string" }, "message_id": {"type": "string", "format": "uuid"}, "created_at": {"type": "integer", "format":"int64"} } } - ] - }, - "StreamEventWfPing": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "type": "object" } ] + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Output data from the workflow." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total time elapsed in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed across all nodes." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "created_by": { + "type": "object", + "additionalProperties": true, + "description": "Creator information. Only present in streaming `workflow_finished` events." + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "Number of exceptions encountered during execution. Only present in streaming `workflow_finished` events." + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "nullable": true, + "description": "Files generated during workflow execution. Only present in streaming `workflow_finished` events." + } + } }, "WorkflowRunDetailResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "workflow_id": { "type": "string", "format": "uuid" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, - "inputs": { "type": "string", "description": "JSON string of input content." }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "JSON object of output content." }, - "error": { "type": "string", "nullable": true }, - "total_steps": { "type": "integer" }, - "total_tokens": { "type": "integer" }, - "created_at": { "type": "integer", "format": "int64" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true } + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the workflow run." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Output data from the workflow." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "Total time elapsed in seconds." + } } }, "FileUploadResponse": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "size": { "type": "integer" }, "extension": { "type": "string" }, "mime_type": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" } } + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique file ID." + }, + "name": { + "type": "string", + "description": "File name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "nullable": true, + "description": "File extension." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Upload timestamp (Unix epoch seconds)." + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "Preview URL for the file." + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "Source URL of the file." + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "Original URL of the file." + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated user." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated tenant." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated conversation." + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "Storage key for the file." + } + } }, "EndUserDetail": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "Tenant ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Application ID." + }, + "type": { + "type": "string", + "description": "End user type. Always `service_api` for Service API users." + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/api-reference/chats/send-chat-message))." + }, + "name": { + "type": "string", + "nullable": true, + "description": "End user name." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request." + }, + "session_id": { + "type": "string", + "description": "Session identifier. Defaults to the `external_user_id` value." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } } }, "WorkflowLogsResponse": { "type": "object", "properties": { - "page": { "type": "integer" }, - "limit": { "type": "integer" }, - "total": { "type": "integer" }, - "has_more": { "type": "boolean" }, - "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowLogItem" } } + "page": { + "type": "integer", + "description": "Current page number." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of log entries." + }, + "has_more": { + "type": "boolean", + "description": "Whether more pages are available." + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "List of workflow log entries." + } } }, "WorkflowLogItem": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "workflow_run": { "$ref": "#/components/schemas/WorkflowRunSummary" }, - "created_from": { "type": "string" }, - "created_by_role": { "type": "string" }, - "created_by_account": { "type": "string", "format": "uuid", "nullable": true }, - "created_by_end_user": { "$ref": "#/components/schemas/EndUserSummary" }, - "created_at": { "type": "integer", "format": "int64" } + "id": { + "type": "string", + "format": "uuid", + "description": "Log entry ID." + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "Source of the workflow run (e.g., `service-api`)." + }, + "created_by_role": { + "type": "string", + "description": "Role of the creator (e.g., `end_user`, `account`)." + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "Account details if created by an admin user.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Account ID." + }, + "name": { + "type": "string", + "description": "Account display name." + }, + "email": { + "type": "string", + "description": "Account email address." + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the log entry was created." + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Additional details for the log entry." + } } }, "WorkflowRunSummary": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "version": { "type": "string" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, - "error": { "type": "string", "nullable": true }, - "elapsed_time": { "type": "number", "format": "float" }, - "total_tokens": { "type": "integer" }, - "total_steps": { "type": "integer" }, - "created_at": { "type": "integer", "format": "int64" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true } + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "version": { + "type": "string", + "description": "Workflow version identifier." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total time elapsed in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "exceptions_count": { + "type": "integer", + "description": "Number of exceptions that occurred during execution." + }, + "triggered_from": { + "type": "string", + "description": "Source that triggered the workflow run. `debugging` for test runs from the editor, `app` for API or app-initiated runs." + } } }, "EndUserSummary": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "type": { "type": "string" }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" } + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "type": { + "type": "string", + "description": "End user type." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the end user is anonymous." + }, + "session_id": { + "type": "string", + "description": "Session identifier." + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "Request body for audio-to-text conversion.", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `30 MB`." + }, + "user": { + "type": "string", + "description": "User identifier." + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "Output text from speech recognition." + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID. Takes priority over `text` when both are provided." + }, + "text": { + "type": "string", + "description": "Speech content to convert." + }, + "user": { + "type": "string", + "description": "User identifier." + }, + "voice": { + "type": "string", + "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." + }, + "streaming": { + "type": "boolean", + "description": "Whether to enable streaming response." + } } }, "AppInfoResponse": { - "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Application name." + }, + "description": { + "type": "string", + "description": "Application description." + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Application tags." + }, + "mode": { + "type": "string", + "description": "Application mode. `completion` for text generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for chatflow apps, `workflow` for workflow apps." + }, + "author_name": { + "type": "string", + "description": "Name of the application author." + } + } }, "WorkflowAppParametersResponse": { - "type": "object", "properties": { "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItem" } }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } } } } }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer" }, "image_file_size_limit": { "type": "integer" }, "audio_file_size_limit": { "type": "integer" }, "video_file_size_limit": { "type": "integer" } } } } + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "nullable": true, + "description": "Opening statement text." + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of suggested questions." + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "Configuration for suggested questions after an answer.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "speech_to_text": { + "type": "object", + "description": "Speech-to-text feature configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "text_to_speech": { + "type": "object", + "description": "Text-to-speech feature configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + }, + "voice": { + "type": "string", + "description": "Voice identifier for TTS." + }, + "language": { + "type": "string", + "description": "Language for TTS." + } + } + }, + "retriever_resource": { + "type": "object", + "description": "Knowledge retrieval citation resource configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "annotation_reply": { + "type": "object", + "description": "Annotation reply feature configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "more_like_this": { + "type": "object", + "description": "More-like-this feature configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "Content moderation feature configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "user_input_form": { + "type": "array", + "items": { + "type": "object", + "oneOf": [ + { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "Display label for the input field." + }, + "variable": { + "type": "string", + "description": "Variable name used in the workflow." + }, + "required": { + "type": "boolean", + "description": "Whether this field is required." + }, + "default": { + "type": "string", + "description": "Default value for the input field." + } + } + } + } + }, + { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "Display label for the paragraph field." + }, + "variable": { + "type": "string", + "description": "Variable name used in the workflow." + }, + "required": { + "type": "boolean", + "description": "Whether this field is required." + }, + "default": { + "type": "string", + "description": "Default value for the paragraph field." + } + } + } + } + }, + { + "title": "Select", + "type": "object", + "properties": { + "select": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "Display label for the select field." + }, + "variable": { + "type": "string", + "description": "Variable name used in the workflow." + }, + "required": { + "type": "boolean", + "description": "Whether this field is required." + }, + "default": { + "type": "string", + "description": "Default selected value." + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of selectable values for this form control." + } + } + } + } + } + ] + }, + "description": "User input form configuration." + }, + "file_upload": { + "type": "object", + "description": "File upload configuration.", + "properties": { + "image": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether image upload is enabled." + }, + "number_limits": { + "type": "integer", + "description": "Maximum number of images that can be uploaded." + }, + "detail": { + "type": "string", + "description": "Image detail level for vision models." + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Allowed transfer methods for image upload. `remote_url` for file URL, `local_file` for uploaded file." + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "System-level parameter limits.", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "Maximum general file size in MB." + }, + "image_file_size_limit": { + "type": "integer", + "description": "Maximum image file size in MB." + }, + "audio_file_size_limit": { + "type": "integer", + "description": "Maximum audio file size in MB." + }, + "video_file_size_limit": { + "type": "integer", + "description": "Maximum video file size in MB." + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "Maximum number of files per workflow execution." + } + } + } + } }, - "UserInputFormItem": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapper" }, { "$ref": "#/components/schemas/ParagraphControlWrapper" }, { "$ref": "#/components/schemas/SelectControlWrapper" } ] }, - "TextInputControlWrapper": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } }, "required":["text-input"] }, - "ParagraphControlWrapper": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } }, "required":["paragraph"] }, - "SelectControlWrapper": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } }, "required":["select"] }, - "TextInputControl": { "type": "object", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } }, - "ParagraphControl": { "type": "object", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } }, - "SelectControl": { "type": "object", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } } }, - "WorkflowWebAppSettingsResponse": { - "type": "object", "properties": { "title": { "type": "string" }, "icon_type": { "type": "string", "enum": ["emoji", "image"] }, "icon": { "type": "string" }, "icon_background": { "type": "string" }, "icon_url": { "type": "string", "format": "url", "nullable": true }, "description": { "type": "string" }, "copyright": { "type": "string" }, "privacy_policy": { "type": "string" }, "custom_disclaimer": { "type": "string" }, "default_language": { "type": "string" }, "show_workflow_steps": { "type": "boolean" } } + "ToolIconDetail": { + "type": "object", + "properties": { + "background": { + "type": "string", + "description": "Background color of the tool icon." + }, + "content": { + "type": "string", + "description": "Emoji or icon content." + } + } }, - "ErrorResponse": { "type": "object", "properties": { "status": { "type": "integer", "nullable": true }, "code": { "type": "string", "nullable": true }, "message": { "type": "string" } } } + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "URL of the icon." + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "Tool icons. Keys are tool names." + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp title." + }, + "chat_color_theme": { + "type": "string", + "description": "Chat color theme." + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "Whether the chat color theme is inverted." + }, + "icon_type": { + "type": "string", + "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." + }, + "icon": { + "type": "string", + "description": "Icon content (emoji or image ID)." + }, + "icon_background": { + "type": "string", + "description": "Icon background color." + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "URL of the icon image." + }, + "description": { + "type": "string", + "description": "WebApp description." + }, + "copyright": { + "type": "string", + "description": "Copyright text." + }, + "privacy_policy": { + "type": "string", + "description": "Privacy policy URL." + }, + "custom_disclaimer": { + "type": "string", + "description": "Custom disclaimer text." + }, + "default_language": { + "type": "string", + "description": "Default language code." + }, + "show_workflow_steps": { + "type": "boolean", + "description": "Whether to show workflow steps." + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "Whether to use the app icon as the answer icon." + } + } + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of paused node IDs." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "Partial outputs at pause time." + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Reasons for pausing." + }, + "status": { + "type": "string", + "description": "Workflow execution status." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total elapsed time in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total steps executed." + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "Node execution ID." + }, + "id": { + "type": "string", + "description": "Agent log entry ID." + }, + "label": { + "type": "string", + "description": "Log label." + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "Parent log entry ID." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the agent step failed." + }, + "status": { + "type": "string", + "description": "Agent step status." + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "Agent step data." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Agent step metadata." + }, + "node_id": { + "type": "string", + "description": "Node ID." + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "Form ID." + }, + "node_id": { + "type": "string", + "description": "Node ID requesting input." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "form_content": { + "type": "string", + "description": "Form content description." + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Form input field definitions." + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Available user actions." + }, + "display_in_ui": { + "type": "boolean", + "description": "Whether to display the form in the UI." + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "Token for form submission." + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "Pre-resolved default values for form fields." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the form expires." + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "Rendered content after form submission." + }, + "action_id": { + "type": "string", + "description": "ID of the action taken." + }, + "action_text": { + "type": "string", + "description": "Text of the action taken." + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp when the form expired." + } + } + } + } + } + ] + } } }, "tags": [ - { "name": "Workflow Execution", "description": "Operations related to executing and managing workflows." }, - { "name": "Files", "description": "File upload and preview operations specific to workflows." }, - { "name": "End Users", "description": "Operations related to end user information." }, - { "name": "Application", "description": "Application settings and info for workflow apps." } + { + "name": "Workflows", + "description": "Operations for executing and managing workflows." + }, + { + "name": "Files", + "description": "File upload and download operations." + }, + { + "name": "End Users", + "description": "Operations related to end user information." + }, + { + "name": "TTS", + "description": "Audio-to-text and text-to-audio conversion." + }, + { + "name": "Applications", + "description": "Application settings, parameters, and metadata." + } ] } diff --git a/ja/api-reference/openapi_chat.json b/ja/api-reference/openapi_chat.json index ee41edfa..0d9be335 100644 --- a/ja/api-reference/openapi_chat.json +++ b/ja/api-reference/openapi_chat.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "チャットアプリAPI", - "description": "チャットアプリケーションはセッションの持続性をサポートしており、以前のチャット履歴を応答のコンテキストとして使用できます。これは、チャットボットやカスタマーサービスAIなどに適用できます。", + "description": "チャットアプリケーションはセッションの永続化をサポートしており、以前のチャット履歴をレスポンスのコンテキストとして使用できます。チャットボットやカスタマーサービス AI などに適用できます。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "APIのベースURL。{api_base_url}をアプリケーション提供の実際のAPIベースURLに置き換えてください。", + "description": "チャットアプリ API のベース URL です。{api_base_url} をアプリケーションに提供された実際の API ベース URL に置き換えてください。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "実際のAPIベースURL" + "description": "API の実際のベース URL" } } } @@ -28,25 +28,27 @@ "summary": "チャットメッセージを送信", "description": "チャットアプリケーションにリクエストを送信します。", "operationId": "sendBasicChatMessageJa", - "tags": ["チャットメッセージ"], + "tags": [ + "チャットメッセージ" + ], "requestBody": { - "description": "チャットメッセージ送信リクエストボディ。", + "description": "チャットメッセージを送信するためのリクエストボディ。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BasicChatRequestJa" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file_ja": { - "summary": "ファイルとカスタム入力を含むストリーミングリクエストの例", + "streaming_example": { + "summary": "リクエスト例 - ストリーミングモード", "value": { "inputs": { - "name": "dify" + "city": "San Francisco" }, - "query": "iPhone 13 Pro Maxの仕様は何ですか？", + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "conversation_id": "", "user": "abc-123", "files": [ { @@ -56,6 +58,16 @@ } ] } + }, + "blocking_example": { + "summary": "リクエスト例 - ブロッキングモード", + "value": { + "inputs": {}, + "query": "What are the specs of the iPhone 13 Pro Max?", + "response_mode": "blocking", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "user": "abc-123" + } } } } @@ -63,101 +75,534 @@ }, "responses": { "200": { - "description": "リクエスト成功。応答のコンテンツタイプと構造はリクエストの`response_mode`パラメータに依存します。\n- `response_mode`が`blocking`の場合、`application/json`形式の`ChatCompletionResponseJa`オブジェクトを返します。\n- `response_mode`が`streaming`の場合、`text/event-stream`形式の`ChunkBasicChatEventJa`オブジェクトストリームを返します。", + "description": "リクエスト成功。コンテンツタイプと構造はリクエストの `response_mode` パラメータに依存します。\n\n- `response_mode` が `blocking` の場合、 `application/json` で `ChatCompletionResponse` オブジェクトを返します。\n- `response_mode` が `streaming` の場合、 `text/event-stream` で `ChunkChatEvent` オブジェクトのストリームを返します。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatCompletionResponseJa" + "$ref": "#/components/schemas/ChatCompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "レスポンス例 - ブロッキングモード", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "chat", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "SSEイベントストリーム。各イベントは'data: 'で始まり、'\\n\\n'で終わります。詳細な構造は`ChunkBasicChatEventJa`を参照してください。" + "description": "サーバー送信イベント (SSE) のストリームです。各イベントは `data: ` プレフィックス付きの JSON オブジェクトで、2 つの改行で終了します。\n\n**SSE パースガイド：**各イベントは `data: ` プレフィックス付きの JSON オブジェクトの行で、`\\n\\n` で終了します。JSON をパースする前に `data: ` プレフィックスを除去してください。JSON 内の `event` フィールドがイベントタイプを決定します。終了イベント（`message_end`、`workflow_finished`、`error` など）を受信するとストリームは終了します。`ping` イベント（10 秒ごとに接続維持のために送信）は無視してください。ストリーム内でエラーイベントが発生しても HTTP ステータスコードは常に `200` です。" + }, + "examples": { + "streamingResponseBasic": { + "summary": "Response Example - Streaming (Basic)", + "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" + }, + "streamingResponseAgent": { + "summary": "Response Example - Streaming (Agent)", + "value": "data: {\"event\": \"agent_thought\", \"id\": \"agent_thought_id_1\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"position\": 1, \"thought\": \"Thinking about calling a tool...\", \"tool\": \"dalle3\", \"tool_input\": \"{\\\"dalle3\\\": {\\\"prompt\\\": \\\"a cute cat\\\"}}\", \"created_at\": 1705395332} data: {\"event\": \"message_file\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"conversation_id\": \"conv123\"} data: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333} data: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}" + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestGenericJa" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundJa" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJa" } + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルは利用できません。\n- `completion_request_error` : テキスト生成に失敗しました。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "conversation_completed": { + "summary": "conversation_completed", + "value": { + "status": 400, + "code": "conversation_completed", + "message": "The conversation has ended. Please start a new conversation." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会話が存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : このアプリケーションへの同時リクエストが多すぎます。\n- `rate_limit_error` : アップストリームのモデルプロバイダーのレート制限を超えました。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } } } }, - "/files/upload": { + "/chat-messages/{task_id}/stop": { "post": { - "summary": "ファイルアップロード", - "description": "メッセージ送信時に使用するためのファイルをアップロードします（現在は画像のみサポート）。画像とテキストのマルチモーダル理解を可能にします。png、jpg、jpeg、webp、gif形式をサポートしています。アップロードされたファイルは現在のエンドユーザーのみが使用できます。", - "operationId": "uploadBasicChatFileJa", - "tags": ["ファイル操作"], + "summary": "生成を停止", + "description": "チャットメッセージ生成タスクを停止します。`streaming` モードでのみサポートされます。", + "operationId": "stopBasicChatMessageGenerationJa", + "tags": [ + "チャットメッセージ" + ], + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "description": "タスク ID です。[チャットメッセージを送信](/api-reference/チャットメッセージ/チャットメッセージを送信) API のストリーミングチャンクレスポンスから取得できます。", + "schema": { + "type": "string" + } + } + ], "requestBody": { - "description": "ファイルアップロードリクエスト。`multipart/form-data`リクエストが必要です。", "required": true, "content": { - "multipart/form-data": { + "application/json": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "user" + ], "properties": { - "file": { "type": "string", "format": "binary", "description": "アップロードするファイル。" }, - "user": { "type": "string", "description": "ユーザー識別子。メッセージ送信インターフェースで渡されたユーザーと一致している必要があります。**重要な注意事項**: Service API は WebApp で作成された対話を共有しません。API を通じて作成された対話は、WebApp インターフェースで作成されたものとは分離されています。" } + "user": { + "type": "string", + "description": "ユーザー識別子。メッセージ送信インターフェースで渡された user と一致する必要があります。" + } + } + }, + "examples": { + "example": { + "summary": "リクエスト例", + "value": { + "user": "abc-123" + } } } } } }, "responses": { - "200": { "description": "ファイルアップロード成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJa" } } } }, - "201": { "description": "ファイル作成成功（代替成功コード）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJa" } } } }, - "400": { "$ref": "#/components/responses/BadRequestFileJa" }, - "413": { "$ref": "#/components/responses/FileTooLargeJa" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileJa" }, - "503": { "$ref": "#/components/responses/S3ErrorFileJa" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJa" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { + "/messages/{message_id}/suggested": { "get": { - "summary": "エンドユーザー取得", - "description": "IDでエンドユーザーを取得します。\n\n他のAPIがエンドユーザーID（例：ファイルアップロードの `created_by`）を返す場合に利用できます。", - "operationId": "getEndUserChatJa", - "tags": ["エンドユーザー"], + "summary": "次の推奨質問を取得", + "description": "現在のメッセージに対する次の質問の提案を取得します。", + "operationId": "getBasicChatSuggestedQuestionsJa", + "tags": [ + "チャットメッセージ" + ], "parameters": [ { - "name": "end_user_id", + "name": "message_id", "in": "path", "required": true, - "description": "エンドユーザーID。", - "schema": { "type": "string", "format": "uuid" } + "description": "メッセージ ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": true, + "description": "ユーザー識別子。", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "エンドユーザーの取得に成功しました。", + "description": "提案された質問の取得に成功しました。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailJa" } + "schema": { + "$ref": "#/components/schemas/SuggestedQuestionsResponse" + }, + "examples": { + "suggestedQuestions": { + "summary": "レスポンス例", + "value": { + "result": "success", + "data": [ + "What colors does the iPhone 13 Pro Max come in?", + "How does the battery compare to iPhone 12?", + "What is the price range?" + ] + } + } + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFoundJa" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJa" } + "400": { + "description": "- `not_chat_app` : アプリモードが API ルートと一致しません。\n- `bad_request` : 推奨質問機能が無効です。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Suggested Questions Is Disabled." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : メッセージが存在しません。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/files/upload": { + "post": { + "summary": "ファイルをアップロード", + "description": "メッセージ送信時に使用するファイルをアップロードします。画像、ドキュメント、音声、動画のマルチモーダル理解が可能です。アップロードされたファイルは現在のエンドユーザーのみが使用できます。", + "operationId": "uploadBasicChatFileJa", + "tags": [ + "ファイル操作" + ], + "requestBody": { + "description": "ファイルアップロードリクエスト。multipart/form-data 形式が必要です。", + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "アップロードするファイル。サポートされるタイプには画像、ドキュメント、音声、動画が含まれます。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。開発者のルールで定義され、アプリケーション内で一意である必要があります。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "ファイルが正常にアップロードされました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : リクエストにファイルが提供されていません。\n- `too_many_files` : 1 回のリクエストにつき 1 ファイルのみ許可されています。\n- `filename_not_exists_error` : アップロードされたファイルにファイル名がありません。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : ファイルサイズの上限を超えています。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 許可されていないファイルタイプです。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } } } }, "/files/{file_id}/preview": { "get": { - "summary": "ファイルプレビュー", - "description": "アップロードされたファイルのプレビューまたはダウンロード。このエンドポイントは、ファイルアップロードAPIを通じて事前にアップロードされたファイルにアクセスすることができます。ファイルは、リクエストしているアプリケーション内のメッセージに属している場合のみアクセス可能です。", + "summary": "ファイルをダウンロード", + "description": "以前[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API 経由でアップロードされたファイルをプレビューまたはダウンロードします。ファイルは、リクエスト元のアプリケーション内のメッセージに属する場合のみアクセスできます。", "operationId": "previewBasicChatFileJa", - "tags": ["ファイル操作"], + "tags": [ + "ファイル操作" + ], "parameters": [ { "name": "file_id", "in": "path", "required": true, - "description": "プレビューするファイルの一意識別子、ファイルアップロードAPIのレスポンスから取得されます。", + "description": "プレビューするファイルの一意の識別子です。[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API のレスポンスから取得します。", "schema": { "type": "string", "format": "uuid" @@ -167,470 +612,3815 @@ "name": "as_attachment", "in": "query", "required": false, - "description": "ファイルを添付ファイルとして強制ダウンロードするかどうか。デフォルトは`false`（ブラウザでプレビュー）です。", + "description": "`true` の場合、ブラウザでプレビューする代わりにファイルを添付ファイルとして強制ダウンロードします。", "schema": { "type": "boolean", "default": false } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子。エンドユーザーのコンテキストに使用されます。", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "ファイルコンテンツが正常に返されました。ヘッダーはファイルタイプとリクエストパラメータに基づいて設定されます。", + "description": "生のファイルコンテンツを返します。`Content-Type` ヘッダーはファイルの MIME タイプに設定されます。`as_attachment` が `true` の場合、ファイルは `Content-Disposition: attachment` としてダウンロード形式で返されます。", "content": { - "image/png": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } - }, - "headers": { - "Content-Type": { - "description": "ファイルのMIMEタイプ", - "schema": { - "type": "string" + } + }, + "403": { + "description": "`file_access_denied` : リクエストされたファイルへのアクセスが拒否されました。", + "content": { + "application/json": { + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } } - }, - "Content-Length": { - "description": "ファイルサイズ（バイト単位、利用可能な場合）", - "schema": { - "type": "integer" + } + } + }, + "404": { + "description": "`file_not_found` : リクエストされたファイルが見つかりません。", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } } - }, - "Content-Disposition": { - "description": "as_attachment=trueの場合、'attachment'に設定されます", + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "summary": "エンドユーザー取得", + "description": "ID を指定してエンドユーザーを取得します。他の API がエンドユーザー ID を返す場合（例：[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード)の `created_by`）に便利です。", + "operationId": "getEndUserChatJa", + "tags": [ + "エンドユーザー" + ], + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "エンドユーザー ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "エンドユーザーを正常に取得しました。", + "content": { + "application/json": { "schema": { - "type": "string" + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "レスポンス例", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } } - }, - "Cache-Control": { - "description": "パフォーマンス用キャッシュヘッダー", - "schema": { - "type": "string", - "example": "public, max-age=3600" + } + } + }, + "404": { + "description": "`end_user_not_found` : エンドユーザーが見つかりません。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } } + } + } + } + } + } + }, + "/messages/{message_id}/feedbacks": { + "post": { + "summary": "メッセージフィードバックを送信", + "description": "メッセージに対するフィードバックを送信します。エンドユーザーはメッセージを `like` または `dislike` で評価でき、任意でテキストフィードバックを提供できます。`rating` に `null` を渡すと、以前送信したフィードバックを取り消せます。", + "operationId": "postBasicChatMessageFeedbackJa", + "tags": [ + "メッセージフィードバック" + ], + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "メッセージ ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MessageFeedbackRequest" }, - "Accept-Ranges": { - "description": "オーディオ/ビデオファイルの場合は'bytes'に設定されます", + "examples": { + "likeFeedback": { + "summary": "リクエスト例", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : メッセージが存在しません。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/app/feedbacks": { + "get": { + "summary": "アプリのフィードバック一覧を取得", + "description": "このアプリケーションのメッセージに対して送信されたすべてのフィードバックのページネーション付きリストを取得します。エンドユーザーと管理者のフィードバックの両方が含まれます。", + "operationId": "getBasicChatAppFeedbacksJa", + "tags": [ + "メッセージフィードバック" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1ページあたりのレコード数。", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } + } + ], + "responses": { + "200": { + "description": "アプリケーションフィードバックのリスト。", + "content": { + "application/json": { "schema": { - "type": "string", - "example": "bytes" + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "rating": "like", + "content": "The response accurately answered my question about product specifications.", + "from_source": "user", + "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "from_account_id": null, + "created_at": "2025-01-16T14:30:29Z", + "updated_at": "2025-01-16T14:30:29Z" + }, + { + "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", + "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", + "rating": "dislike", + "content": "The answer was too vague and did not address the specific pricing question.", + "from_source": "user", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", + "from_account_id": null, + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" + } + ] + } + } + } + } + } + } + } + } + }, + "/conversations": { + "get": { + "summary": "会話一覧を取得", + "description": "現在のユーザーの会話リストを、最近アクティブな順に取得します。", + "operationId": "getBasicChatConversationsListJa", + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子。", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "現在のページの最後のレコードの ID（ページネーション用）です。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "返すレコード数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "sort_by", + "in": "query", + "required": false, + "description": "ソートフィールドです。降順にするには '-' プレフィックスを使用します。", + "schema": { + "type": "string", + "enum": [ + "created_at", + "-created_at", + "updated_at", + "-updated_at" + ], + "default": "-updated_at" + } + } + ], + "responses": { + "200": { + "description": "会話リストの取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationsListResponse" + }, + "examples": { + "conversationsList": { + "summary": "レスポンス例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } } } } }, "400": { - "description": "不正なリクエスト。可能なエラーコード:\n- `invalid_param`: 異常なパラメータ入力。", + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } - } - } - }, - "403": { - "description": "禁止。可能なエラーコード:\n- `file_access_denied`: ファイルアクセス拒否またはファイルが現在のアプリケーションに属していません。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } } } }, "404": { - "description": "見つかりません。可能なエラーコード:\n- `file_not_found`: ファイルが見つからないか削除されています。", + "description": "`not_found` : 前の会話が存在しません（無効な `last_id`）。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } - } - } - }, - "500": { - "description": "内部サーバーエラー。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } + "examples": { + "last_conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Last Conversation Not Exists." + } + } + } } } } } } }, - "/chat-messages/{task_id}/stop": { - "post": { - "summary": "生成停止", - "description": "チャットメッセージの生成を停止します。ストリーミングモードでのみサポートされています。", - "operationId": "stopBasicChatMessageGenerationJa", - "tags": ["チャットメッセージ"], - "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "タスクID、ストリーミングチャンクの返り値から取得できます。", "schema": { "type": "string", "format": "uuid" } } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["user"], "properties": { "user": { "type": "string", "description": "ユーザー識別子。メッセージ送信インターフェースで渡されたユーザーと一致している必要があります。**重要な注意事項**: Service API は WebApp で作成された対話を共有しません。API を通じて作成された対話は、WebApp インターフェースで作成されたものとは分離されています。" } } } } } }, - "responses": { "200": { "$ref": "#/components/responses/SuccessResultJa" } } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "メッセージフィードバック", - "description": "エンドユーザーはフィードバックメッセージを提供でき、アプリケーション開発者が期待される出力を最適化するのに役立ちます。", - "operationId": "postBasicChatMessageFeedbackJa", - "tags": ["メッセージフィードバック"], - "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "メッセージID。", "schema": { "type": "string", "format": "uuid" } } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestJa" } } } }, - "responses": { "200": { "$ref": "#/components/responses/SuccessResultJa" } } - } - }, - "/app/feedbacks": { - "get": { - "summary": "アプリのメッセージの「いいね」とフィードバックを取得", - "description": "アプリのエンドユーザーからのフィードバックや「いいね」を取得します。", - "operationId": "getBasicChatAppFeedbacksJa", - "tags": ["メッセージフィードバック"], - "parameters": [ { "$ref": "#/components/parameters/PageQueryParamJa" }, { "$ref": "#/components/parameters/LimitQueryParamJa" } ], - "responses": { "200": { "description": "アプリのフィードバックリストを正常に取得しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseJa" } } } } } - } - }, - "/messages/{message_id}/suggested": { - "get": { - "summary": "次の推奨質問", - "description": "現在のメッセージに対する次の質問の提案を取得します。", - "operationId": "getBasicChatSuggestedQuestionsJa", - "tags": ["チャットメッセージ"], - "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "メッセージID。", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/UserQueryParamJa" } ], - "responses": { "200": { "description": "推奨質問リストを正常に取得しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponseJa" } } } } } - } - }, "/messages": { "get": { - "summary": "会話履歴メッセージを取得", - "description": "スクロールロード形式で過去のチャット記録を返し、最初のページは最新の`{limit}`メッセージを返します。つまり、逆順です。", + "summary": "会話履歴メッセージ一覧を取得", + "description": "スクロール読み込み形式で過去のチャット記録を返します。最初のページは最新の `limit` 件のメッセージを返します（時系列の逆順）。", "operationId": "getBasicChatConversationHistoryJa", - "tags": ["会話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdQueryParamJa" }, { "$ref": "#/components/parameters/UserQueryParamJa" }, { "name": "first_id", "in": "query", "description": "現在のページの最初のチャット記録のID、デフォルトはnullです。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, { "$ref": "#/components/parameters/LimitQueryParamDefault20Ja" } ], - "responses": { "200": { "description": "会話履歴メッセージを正常に取得しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicConversationHistoryResponseJa" } } } } } + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子。", + "schema": { + "type": "string" + } + }, + { + "name": "first_id", + "in": "query", + "required": false, + "description": "現在のページの最初のチャット記録の ID です。デフォルトは `null`（最新のメッセージを取得）です。次のページを取得するには、現在のリストの最初のメッセージの ID を使用して、より古いメッセージを取得します。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "リクエストごとに返すチャット履歴メッセージの数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "会話履歴の取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "レスポンス例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "parent_message_id": null, + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "status": "normal", + "error": null, + "message_files": [], + "feedback": { + "rating": "like" + }, + "retriever_resources": [], + "agent_thoughts": [], + "created_at": 1705407629, + "extra_contents": [] + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 会話が存在しません。\n- `not_found` : 最初のメッセージが存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "first_message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "First Message Not Exists." + } + } + } + } + } + } + } } }, - "/conversations": { + "/conversations/{conversation_id}/variables": { "get": { - "summary": "会話を取得", - "description": "現在のユーザーの会話リストを取得し、デフォルトで最新の20件を返します。", - "operationId": "getBasicChatConversationsListJa", - "tags": ["会話管理"], - "parameters": [ { "$ref": "#/components/parameters/UserQueryParamJa" }, { "$ref": "#/components/parameters/LastIdQueryParamJa" }, { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Ja" }, { "$ref": "#/components/parameters/SortByQueryParamJa" } ], - "responses": { "200": { "description": "会話リストを正常に取得しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsListResponseJa" } } } } } - } - }, - "/conversations/{conversation_id}": { - "delete": { - "summary": "会話を削除", - "description": "指定された会話を削除します。", - "operationId": "deleteBasicChatConversationJa", - "tags": ["会話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJa" } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["user"], "properties": { "user": { "type": "string", "description": "ユーザー識別子。**重要な注意事項**: Service API は WebApp で作成された対話を共有しません。API を通じて作成された対話は、WebApp インターフェースで作成されたものとは分離されています。" } } } } } }, - "responses": { "204": { "description": "会話の削除に成功しました。コンテンツはありません。" } } + "summary": "会話変数の取得", + "description": "特定の会話から変数を取得します。", + "operationId": "getBasicChatConversationVariablesJa", + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子です。", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "現在のページの最後のレコードの ID（ページネーション用）です。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "返すレコード数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "variable_name", + "in": "query", + "required": false, + "description": "指定した名前で変数をフィルタリングします。", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + } + ], + "responses": { + "200": { + "description": "会話変数の取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariablesResponse" + }, + "examples": { + "conversationVariables": { + "summary": "レスポンス例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "dark_mode", + "description": "ユーザー設定", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会話が存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } } }, "/conversations/{conversation_id}/name": { "post": { "summary": "会話の名前を変更", - "description": "セッションの名前を変更します。セッション名は、複数のセッションをサポートするクライアントでの表示に使用されます。", + "description": "会話の名前を変更するか、自動的に生成します。会話名は複数の会話をサポートするクライアントでの表示に使用されます。", "operationId": "renameBasicChatConversationJa", - "tags": ["会話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJa" } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequestJa" } } } }, - "responses": { "200": { "description": "会話の名前変更に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameResponseJa" } } } } } + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationRenameRequest" + }, + "examples": { + "renameExample": { + "summary": "リクエスト例", + "value": { + "name": "iPhone Specs Chat", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "会話が正常に名前変更されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationListItem" + }, + "examples": { + "renamedConversation": { + "summary": "レスポンス例", + "value": { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会話が存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } } }, - "/conversations/{conversation_id}/variables": { - "get": { - "summary": "会話変数の取得", - "description": "特定の会話から変数を取得します。このエンドポイントは、会話中に取得された構造化データを抽出するのに役立ちます。", - "operationId": "getBasicChatConversationVariablesJa", - "tags": ["会話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJa" }, { "$ref": "#/components/parameters/UserQueryParamJa" }, { "$ref": "#/components/parameters/LastIdQueryParamJa" }, { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Ja" }, { "$ref": "#/components/parameters/VariableNameQueryParamJa" } ], - "responses": { "200": { "description": "会話変数を正常に取得しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariablesResponseJa" } } } }, "404": { "$ref": "#/components/responses/ConversationNotFoundJa" } } + "/conversations/{conversation_id}/variables/{variable_id}": { + "put": { + "summary": "会話変数を更新", + "description": "特定の会話変数の値を更新します。値は期待される型と一致する必要があります。", + "operationId": "updateChatConversationVariableJa", + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "variable_id", + "in": "path", + "required": true, + "description": "Variable ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableUpdateRequest" + }, + "examples": { + "updateStringVariable": { + "summary": "リクエスト例", + "value": { + "value": "new value", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "変数が正常に更新されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableItem" + }, + "examples": { + "updatedVariable": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "new value", + "description": "ユーザー設定", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : アプリモードが API ルートと一致しません。\n- `bad_request` : 変数値の型が一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "type_mismatch": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Value type mismatch: expected string, got integer." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 会話が存在しません。\n- `not_found` : 会話変数が存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "variable_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Variable Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}": { + "delete": { + "summary": "会話を削除", + "description": "会話を削除します。", + "operationId": "deleteBasicChatConversationJa", + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user": { + "type": "string", + "description": "ユーザー識別子です。" + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "リクエスト例" + } + } + } + } + }, + "responses": { + "204": { + "description": "会話が正常に削除されました。" + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会話が存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } } }, "/audio-to-text": { "post": { - "summary": "音声からテキストへ", - "description": "オーディオファイルをテキストに変換します。サポートされている形式：mp3, mp4, mpeg, mpga, m4a, wav, webm。ファイルサイズ制限：15MB。", + "summary": "音声をテキストに変換", + "description": "音声ファイルをテキストに変換します。サポートされる形式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファイルサイズの上限は `30 MB` です。", "operationId": "basicChatAudioToTextJa", - "tags": ["音声とテキスト変換"], - "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequestJa" } } } }, - "responses": { "200": { "description": "音声からテキストへの変換に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponseJa" } } } } } + "tags": [ + "音声・テキスト変換" + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "音声からテキストへの変換に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "レスポンス例", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `no_audio_uploaded` : 音声ファイルがアップロードされていません。\n- `provider_not_support_speech_to_text` : モデルプロバイダーが音声認識をサポートしていません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルはこの操作をサポートしていません。\n- `completion_request_error` : 音声認識リクエストに失敗しました。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音声ファイルサイズが上限を超えています。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 許可されていない音声タイプです。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } } }, "/text-to-audio": { "post": { - "summary": "テキストから音声へ", - "description": "テキストコンテンツを音声に変換します。", + "summary": "テキストを音声に変換", + "description": "テキストを音声に変換します。", "operationId": "basicChatTextToAudioJa", - "tags": ["音声とテキスト変換"], - "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TextToAudioFormRequestJa" } } } }, - "responses": { "200": { "description": "音声ファイルの生成に成功しました。", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } } } + "tags": [ + "音声・テキスト変換" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "リクエスト例", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "生成された音声ファイルを返します。`Content-Type` ヘッダーは音声の MIME タイプ（例：`audio/wav`、`audio/mp3`）に設定されます。`streaming` が `true` の場合、音声はチャンク転送エンコーディングでストリーミングされます。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルはこの操作をサポートしていません。\n- `completion_request_error` : テキスト読み上げリクエストに失敗しました。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } } }, "/info": { "get": { "summary": "アプリケーションの基本情報を取得", + "description": "このアプリケーションの基本情報（名前、説明、タグ、モード）を取得します。", "operationId": "getBasicChatAppInfoJa", - "tags": ["アプリケーション設定"], - "responses": { "200": { "description": "アプリケーションの基本情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseJa" } } } } } + "tags": [ + "アプリケーション設定" + ], + "responses": { + "200": { + "description": "アプリケーションの基本情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "レスポンス例", + "value": { + "name": "My Chat App", + "description": "便利なカスタマーサービスチャットボット。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "chat", + "author_name": "Dify Team" + } + } + } + } + } + } + } } }, "/parameters": { "get": { "summary": "アプリケーションのパラメータ情報を取得", - "description": "ページに入る際に、機能、入力パラメータ名、タイプ、デフォルト値などの情報を取得するために使用されます。", + "description": "アプリケーションの入力フォーム設定（機能スイッチ、入力パラメータ名、タイプ、デフォルト値）を取得します。", "operationId": "getBasicChatAppParametersJa", - "tags": ["アプリケーション設定"], - "responses": { "200": { "description": "アプリケーションのパラメータ情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicChatAppParametersResponseJa" } } } } } + "tags": [ + "アプリケーション設定" + ], + "responses": { + "200": { + "description": "アプリケーションパラメータ情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "レスポンス例", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } } }, "/meta": { "get": { "summary": "アプリケーションのメタ情報を取得", - "description": "このアプリケーションのツールのアイコンを取得するために使用されます。", + "description": "このアプリケーションのメタデータ（ツールアイコンやその他の設定詳細）を取得します。", "operationId": "getBasicChatAppMetaJa", - "tags": ["アプリケーション設定"], - "responses": { "200": { "description": "アプリケーションのメタ情報を正常に取得しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponseJa" } } } } } + "tags": [ + "アプリケーション設定" + ], + "responses": { + "200": { + "description": "アプリケーションのメタ情報を正常に取得しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "レスポンス例", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } } }, "/site": { "get": { - "summary": "アプリのWebApp設定を取得", - "description": "アプリのWebApp設定を取得するために使用します。", + "summary": "アプリの WebApp 設定を取得", + "description": "このアプリケーションの WebApp 設定（サイト設定、テーマ、カスタマイズオプション）を取得します。", "operationId": "getBasicChatWebAppSettingsJa", - "tags": ["アプリケーション設定"], - "responses": { "200": { "description": "WebApp設定。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseJa" } } } } } + "tags": [ + "アプリケーション設定" + ], + "responses": { + "200": { + "description": "アプリケーションの WebApp 設定。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "レスポンス例", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "便利なカスタマーサービスチャットボット。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このアプリケーションのサイトが見つからないか、ワークスペースがアーカイブされています。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } + } + }, + "/apps/annotations": { + "post": { + "summary": "アノテーションを作成", + "description": "新しいアノテーションを作成します。アノテーションは、アプリがレスポンスを生成する代わりに直接マッチして返すことができる、事前定義された質問と回答のペアを提供します。", + "operationId": "createChatAnnotationJa", + "tags": [ + "アノテーション管理" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAnnotationRequest" + }, + "examples": { + "createAnnotation": { + "summary": "リクエスト例", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "アノテーションが正常に作成されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "createdAnnotation": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 0, + "created_at": 1705407629 + } + } + } + } + } + } + } + }, + "get": { + "summary": "アノテーションリストを取得", + "description": "アプリケーションのアノテーションをページネーションリストで取得します。キーワード検索によるフィルタリングをサポートしています。", + "operationId": "listChatAnnotationsJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1 ページあたりの件数です。", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "keyword", + "in": "query", + "description": "質問または回答の内容でアノテーションをフィルタリングするためのキーワードです。", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "アノテーションリストの取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationListResponse" + }, + "examples": { + "annotationList": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 5, + "created_at": 1705407629 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + } + } + } + }, + "/apps/annotations/{annotation_id}": { + "put": { + "summary": "アノテーションを更新", + "description": "既存のアノテーションの質問と回答を更新します。", + "operationId": "updateChatAnnotationJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "更新するアノテーションの一意の識別子です。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateAnnotationRequest" + }, + "examples": { + "updateAnnotation": { + "summary": "リクエスト例", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "アノテーションが正常に更新されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "updatedAnnotation": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", + "hit_count": 5, + "created_at": 1705407629 + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : アノテーションを編集する権限がありません。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : アノテーションが存在しません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } + } + }, + "delete": { + "summary": "アノテーションを削除", + "description": "アノテーションとその関連するヒット履歴を削除します。", + "operationId": "deleteChatAnnotationJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "削除するアノテーションの一意の識別子です。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "アノテーションが正常に削除されました。" + }, + "403": { + "description": "`forbidden` : アノテーションを編集する権限がありません。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : アノテーションが存在しません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } + } + } + }, + "/apps/annotation-reply/{action}": { + "post": { + "summary": "アノテーション返信を設定", + "description": "アノテーション返信機能を有効または無効にします。有効にする場合は埋め込みモデルの設定が必要です。非同期で実行されます——[アノテーション返信の初期設定タスクステータスを取得](/api-reference/アノテーション管理/アノテーション返信の初期設定タスクステータスを取得) で進捗を追跡します。", + "operationId": "setChatAnnotationReplyJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "実行するアクションです。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" + }, + "examples": { + "enableAnnotationReply": { + "summary": "リクエスト例", + "value": { + "score_threshold": 0.9, + "embedding_provider_name": "openai", + "embedding_model_name": "text-embedding-3-small" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "アノテーション返信設定タスクが開始されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" + }, + "examples": { + "annotationReplyResponse": { + "summary": "レスポンス例", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "waiting" + } + } + } + } + } + } + } + } + }, + "/apps/annotation-reply/{action}/status/{job_id}": { + "get": { + "summary": "アノテーション返信の初期設定タスクステータスを取得", + "description": "[アノテーション返信を設定](/api-reference/アノテーション管理/アノテーション返信を設定) で開始された非同期アノテーション返信設定ジョブのステータスを取得します。", + "operationId": "getChatAnnotationReplyStatusJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "アクションタイプです。[アノテーション返信を設定](/api-reference/アノテーション管理/アノテーション返信を設定) の呼び出しと一致する必要があります。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "[アノテーション返信を設定](/api-reference/アノテーション管理/アノテーション返信を設定) から返されたジョブ ID です。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "タスクステータスの取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "レスポンス例", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 指定されたジョブが存在しません。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "The job does not exist." + } + } + } + } + } + } + } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "APIキー認証。すべてのAPIリクエストにおいて、Authorization HTTPヘッダーにAPIキーを含めてください。形式：Bearer {API_KEY}。APIキーの漏洩を防ぐため、APIキーはクライアント側で共有または保存せず、サーバー側で保存することを強くお勧めします。" } - }, - "parameters": { - "PageQueryParamJa": { "name": "page", "in": "query", "description": "（任意）ページ番号。デフォルト値：1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamJa": { "name": "limit", "in": "query", "description": "（任意）1ページあたりの件数。デフォルト値：20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Ja": { "name": "limit", "in": "query", "description": "1回のリクエストで返すレコードの数、デフォルトは20です。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100Ja": { "name": "limit", "in": "query", "description": "1回のリクエストで返すレコードの数、デフォルトは20件です。最大100、最小1。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParamJa": { "name": "user", "in": "query", "required": true, "description": "ユーザー識別子。アプリケーション内で開発者によって一意に定義される必要があります。**重要な注意事項**: Service API は WebApp で作成された対話を共有しません。API を通じて作成された対話は、WebApp インターフェースで作成されたものとは分離されています。", "schema": { "type": "string" } }, - "ConversationIdQueryParamJa": { "name": "conversation_id", "in": "query", "required": true, "description": "会話ID。", "schema": { "type": "string", "format": "uuid" } }, - "LastIdQueryParamJa": { "name": "last_id", "in": "query", "description": "(Optional)現在のページの最後のレコードのID、デフォルトはnullです。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, - "SortByQueryParamJa": { "name": "sort_by", "in": "query", "description": "(Optional)ソートフィールド、デフォルト：-updated_at（更新時間で降順にソート）。利用可能な値：created_at, -created_at, updated_at, -updated_at。フィールドの前の記号「-」は逆順を表します。", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParamJa": { "name": "conversation_id", "in": "path", "required": true, "description": "会話ID。", "schema": { "type": "string", "format": "uuid" } }, - "VariableNameQueryParamJa": { "name": "variable_name", "in": "query", "description": "(Optional)変数名でフィルタリングします。", "schema": { "type": "string" } } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 認証です。すべての API リクエストにおいて、`Authorization` HTTP ヘッダーに `Bearer ` プレフィックスを付けた API Key を含めてください。例：`Authorization: Bearer {API_KEY}`。**API Key はサーバーサイドに保存し、クライアントサイドで共有・保存しないことを強く推奨します。API Key の漏洩は深刻な結果につながる可能性があります。**" + } }, "responses": { - "BadRequestGenericJa": { "description": "リクエストパラメータエラー。考えられる原因：invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "BadRequestFileJa": { "description": "ファイル操作リクエストエラー。考えられる原因：no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "FileTooLargeJa": { "description": "ファイルが大きすぎます (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "UnsupportedFileTypeFileJa": { "description": "サポートされていないファイルタイプ (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "S3ErrorFileJa": { "description": "S3ストレージサービスエラー。考えられる原因：s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "InternalServerErrorJa": { "description": "内部サーバーエラー。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "SuccessResultJa": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFoundJa": { "description": "会話が存在しません。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "EndUserNotFoundJa": { "description": "エンドユーザーが見つかりません。エラーコード：`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } } + "SuccessResult": { + "description": "操作が成功しました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "結果ステータス。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "BasicChatRequestJa": { - "type": "object", "required": ["query", "user"], + "ChatRequest": { + "type": "object", + "required": [ + "inputs", + "query", + "user" + ], "properties": { - "query": { "type": "string", "description": "ユーザー入力/質問内容。" }, - "inputs": { "type": "object", "description": "アプリで定義されたさまざまな変数値の入力を許可します。デフォルトは`{}`。", "additionalProperties": true, "default": {} }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "応答の返却モード。streaming（推奨）はSSEベース。blockingは実行完了後に結果を返します（Cloudflareの100秒タイムアウト制限あり；エージェントアシスタントモードではサポートされていません）。" }, - "user": { "type": "string", "description": "ユーザー識別子、アプリケーション内で一意である必要があります。**重要な注意事項**: Service API は WebApp で作成された対話を共有しません。API を通じて作成された対話は、WebApp インターフェースで作成されたものとは分離されています。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID、以前のチャット記録に基づいて会話を続けるには、前のメッセージのconversation_idを渡す必要があります。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/BasicInputFileObjectJa" }, "description": "アップロードされたファイルリスト。現在は画像タイプのみサポート。" }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "タイトルを自動生成します。デフォルトは`true`です。" } + "query": { + "type": "string", + "description": "ユーザーの入力/質問内容です。" + }, + "inputs": { + "type": "object", + "description": "アプリで定義されたさまざまな変数の値を入力できます。キーと値のペアを含みます。アプリが期待する変数名と型については、[アプリケーションのパラメータ情報を取得](/api-reference/アプリケーション設定/アプリケーションのパラメータ情報を取得) レスポンスの `user_input_form` フィールドを参照してください。", + "additionalProperties": true + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "レスポンスの返却モードです。`streaming`（推奨）は SSE を使用します。`blocking` は完了後に返します（長時間の処理では中断される場合があります。エージェントアシスタントモードではサポートされていません）。Cloudflare のタイムアウトは `100 s` です。省略した場合、デフォルトはブロッキング動作になります。" + }, + "user": { + "type": "string", + "description": "アプリケーション内で一意のユーザー識別子です。この識別子はデータアクセスの範囲を限定します——会話、メッセージ、ファイルは同じ `user` 値でクエリした場合にのみ表示されます。" + }, + "conversation_id": { + "type": "string", + "description": "会話を継続するための会話 ID です。前のメッセージの `conversation_id` を渡します。新しい会話を開始するには、このフィールドを省略するか空文字列を渡します。レスポンスで `conversation_id` が返されます——以降のメッセージでこの値を渡すとその会話を継続できます。" + }, + "files": { + "type": "array", + "description": "マルチモーダル理解用のファイルリストです。画像、ドキュメント、音声、動画を含みます。ローカルファイルを添付するには、まず [ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) でアップロードし、返された `id` を `upload_file_id` として `transfer_method: local_file` で使用します。", + "items": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "ファイルタイプ。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "転送方法です。ファイル URL の場合は `remote_url`、アップロードファイルの場合は `local_file` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファイル URL（`transfer_method` が `remote_url` の場合は必須）です。" + }, + "upload_file_id": { + "type": "string", + "description": "[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API から取得したアップロード済みファイル ID です（`transfer_method` が `local_file` の場合は必須）。" + } + } + } + }, + "auto_generate_name": { + "type": "boolean", + "description": "会話タイトルを自動生成します。`false` の場合、[会話の名前を変更](/api-reference/会話管理/会話の名前を変更) API で `auto_generate: true` を設定して非同期でタイトルを生成します。", + "default": true + } } }, - "BasicInputFileObjectJa": { - "type": "object", "required": ["type", "transfer_method"], + "ChatCompletionResponse": { + "type": "object", "properties": { - "type": { "type": "string", "enum": ["image"], "description": "サポートされているタイプ：`image`（現在は画像タイプのみサポート）。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "転送方法。remote_url は画像URL / local_file はファイルアップロード用" }, - "url": { "type": "string", "format": "url", "description": "画像URL（転送方法が remote_url の場合）" }, - "upload_file_id": { "type": "string", "format":"uuid", "description": "アップロードされたファイルID、事前にファイルアップロードAPIで取得する必要があります（転送方法が local_file の場合）" } + "event": { + "type": "string", + "description": "イベントタイプ。`message` に固定されています。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "リクエスト追跡およびレスポンス停止 API 用のタスク ID です。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "このレスポンスイベントの一意 ID です。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "一意のメッセージ ID です。フィードバックや推奨質問のエンドポイントを呼び出す際に `message_id` パラメータとして使用します。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "mode": { + "type": "string", + "description": "アプリモード、`chat` 固定です。" + }, + "answer": { + "type": "string", + "description": "完全なレスポンスコンテンツ。" + }, + "metadata": { + "type": "object", + "description": "使用量と検索リソースを含むメタデータ。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用された検索リソースのリスト。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "メッセージ作成タイムスタンプ（Unix エポック秒）。" + } + } + }, + "ChunkChatEvent": { + "type": "object", + "description": "ストリーミングモードにおける Server-Sent Event チャンクのベーススキーマです。", + "properties": { + "event": { + "type": "string", + "description": "イベントの種類です。", + "enum": [ + "message", + "agent_message", + "tts_message", + "tts_message_end", + "agent_thought", + "message_file", + "message_end", + "message_replace", + "error", + "ping" + ] + } }, - "anyOf": [ + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventChatMessage", + "agent_message": "#/components/schemas/StreamEventChatAgentMessage", + "tts_message": "#/components/schemas/StreamEventChatTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", + "agent_thought": "#/components/schemas/StreamEventChatAgentThought", + "message_file": "#/components/schemas/StreamEventChatMessageFile", + "message_end": "#/components/schemas/StreamEventChatMessageEnd", + "message_replace": "#/components/schemas/StreamEventChatMessageReplace", + "error": "#/components/schemas/StreamEventChatError", + "ping": "#/components/schemas/StreamEventChatPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "description": "ストリームイベントの基本プロパティです。", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "タスク ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "一意のメッセージ ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + } + } + }, + "StreamEventChatMessage": { + "allOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "$ref": "#/components/schemas/ChunkChatEvent" }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format":"uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } - } - ] - }, - "ChatCompletionResponseJa": { - "type": "object", "description": "ブロッキングモードでの完全なアプリ結果。", - "properties": { - "event": { "type": "string", "example": "message", "description": "イベントタイプ、固定で `message`。" }, - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "id": { "type": "string", "format": "uuid", "description": "ユニークID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。" }, - "mode": { "type": "string", "example": "chat", "description": "アプリモード、`chat`として固定。" }, - "answer": { "type": "string", "description": "完全な応答内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataJa" }, - "created_at": { "type": "integer", "format": "int64", "description": "メッセージ作成タイムスタンプ。" } - } - }, - "ResponseMetadataJa": { - "type": "object", "description": "メタデータ。", - "properties": { "usage": { "$ref": "#/components/schemas/UsageJa" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJa" }, "description": "引用と帰属リスト。" } } - }, - "ChunkBasicChatEventJa": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "agent_message", "agent_thought", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], "description": "イベントタイプ。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "message": "#/components/schemas/StreamEventChatMessageJa", "agent_message": "#/components/schemas/StreamEventAgentMessageJa", - "agent_thought": "#/components/schemas/StreamEventAgentThoughtJa", "message_file": "#/components/schemas/StreamEventMessageFileJa", - "message_end": "#/components/schemas/StreamEventMessageEndJa", "tts_message": "#/components/schemas/StreamEventTtsMessageJa", - "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndJa", "message_replace": "#/components/schemas/StreamEventMessageReplaceJa", - "error": "#/components/schemas/StreamEventErrorJa", "ping": "#/components/schemas/StreamEventPingJa" - }} - }, - "StreamEventBaseChatJa": { - "type": "object", "properties": { - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。" }, - "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } - } - }, - "StreamEventChatMessageJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLMが返したテキストチャンク内容。" } } } ] }, - "StreamEventAgentMessageJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLMが返したテキストチャンク内容（エージェントモード）。" } } } ] }, - "StreamEventAgentThoughtJa": { - "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, - { "type": "object", "required": ["id", "task_id", "message_id", "position", "created_at", "conversation_id"], + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "エージェント思考ID。" }, - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, - "position": { "type": "integer", "description": "エージェント思考のメッセージ内での位置。" }, - "thought": { "type": "string", "nullable": true, "description": "エージェントの思考内容。" }, - "observation": { "type": "string", "nullable": true, "description": "ツール呼び出しからの応答。" }, - "tool": { "type": "string", "nullable": true, "description": "使用されたツールのリスト、;で区切られます。" }, - "tool_input": { "type": "string", "nullable": true, "description": "ツールの入力、JSON形式の文字列。" }, - "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" }, - "message_files": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "ファイルID" }, "description": "現在のエージェント思考に関連するファイルIDのリスト。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。" } + "answer": { + "type": "string", + "description": "LLM が返したテキストチャンクです。" + } } } ] }, - "StreamEventMessageFileJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ファイル一意ID。" }, "type": { "type": "string", "enum": ["image"], "description": "ファイルタイプ、現在は'image'のみ許可。" }, "belongs_to": { "type": "string", "enum": ["assistant"], "description": "所属、ここでは'assistant'のみ。" }, "url": { "type": "string", "format": "url", "description": "ファイルのリモートURL。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。" } } } ] }, - "StreamEventMessageEndJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataJa" } } } ] }, - "StreamEventTtsMessageJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64エンコードされたオーディオブロック。" } } } ] }, - "StreamEventTtsMessageEndJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空の文字列。" } } } ] }, - "StreamEventMessageReplaceJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "置換内容（すべてのLLM返信テキストを直接置換）。" } } } ] }, - "StreamEventErrorJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "type": "object", "required": ["task_id", "status", "code", "message"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "一意のメッセージID（エラーイベントでは存在しない場合があります）。" }, "status": { "type": "integer", "description": "HTTPステータスコード。" }, "code": { "type": "string", "description": "エラーコード。" }, "message": { "type": "string", "description": "エラーメッセージ。" } } } ] }, - "StreamEventPingJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "type": "object", "description": "接続を維持するために10秒ごとにpingイベントが発生します。" } ] }, - "UsageJa": { "type": "object", "description": "モデル使用情報。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceJa": { "type": "object", "description": "引用と帰属情報。", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } }, - "FileUploadResponseJa": { "type": "object", "description": "ファイルアップロード成功後の応答。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "ファイル名。" }, "size": { "type": "integer", "description": "ファイルサイズ（バイト）。" }, "extension": { "type": "string", "description": "ファイル拡張子。" }, "mime_type": { "type": "string", "description": "ファイルのMIMEタイプ。" }, "created_by": { "type": "string", "format": "uuid", "description": "エンドユーザーID。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } }, - "EndUserDetailJa": { + "StreamEventChatAgentMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "answer": { + "type": "string", + "description": "LLM が返したテキストチャンク（エージェントモード）です。" + } + } + } + ] + }, + "StreamEventChatTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリームイベント（base64 エンコードの Mp3）です。自動再生が有効な場合に利用できます。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 エンコードされた MP3 音声チャンク。すべてのチャンクを順番にデコードして連結すると、完全な音声ファイルが生成されます。" + } + } + } + ] + }, + "StreamEventChatTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリーム終了イベント。", + "properties": { + "audio": { + "type": "string", + "description": "空の文字列。音声ストリームの終了を示します。" + } + } + } + ] + }, + "StreamEventChatAgentThought": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "エージェントの思考、LLM の推論、ツール呼び出しの詳細（エージェントモード）です。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "エージェント思考 ID です。" + }, + "position": { + "type": "integer", + "description": "メッセージ内のシーケンスにおけるこの思考の位置です。" + }, + "thought": { + "type": "string", + "description": "LLM が思考している内容です。" + }, + "observation": { + "type": "string", + "description": "ツール呼び出しからのレスポンスです。" + }, + "tool": { + "type": "string", + "description": "呼び出されたツールのリスト（`;` で区切り）です。" + }, + "tool_input": { + "type": "string", + "description": "ツールの入力（JSON 形式）です。" + }, + "message_files": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "description": "この思考に関連するファイルのファイル ID です。" + } + } + } + ] + }, + "StreamEventChatMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "メッセージファイルイベント。ツールによって作成された新しいファイルです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ファイルの一意の ID。" + }, + "type": { + "type": "string", + "description": "ファイルタイプ（例：`image`）。" + }, + "belongs_to": { + "type": "string", + "description": "このファイルの所有者です。ツールが生成したファイルの場合は常に `assistant` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファイルのリモート URL。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + } + } + } + ] + }, + "StreamEventChatMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "メッセージ終了イベント、ストリーミングが終了しました。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "メッセージの一意な ID。" + }, + "metadata": { + "type": "object", + "description": "使用量と検索リソースを含むメタデータ。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用された検索リソースのリスト。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } + ] + }, + "StreamEventChatMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "メッセージコンテンツ置換イベント（例：コンテンツモデレーションによるもの）。", + "properties": { + "answer": { + "type": "string", + "description": "置換コンテンツ。" + }, + "reason": { + "type": "string", + "description": "コンテンツ置換の理由。" + } + } + } + ] + }, + "StreamEventChatError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ストリーミング中のエラーイベント。", + "properties": { + "status": { + "type": "integer", + "description": "HTTP ステータスコード。" + }, + "code": { + "type": "string", + "description": "エラーコード。" + }, + "message": { + "type": "string", + "description": "エラーメッセージ。" + } + } + } + ] + }, + "StreamEventChatPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "接続を維持するための Ping イベント。" + } + ] + }, + "Usage": { + "type": "object", + "description": "モデルの使用情報です。", + "properties": { + "prompt_tokens": { + "type": "integer", + "description": "プロンプト内のトークン数。" + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "プロンプトトークンあたりの単価。" + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "プロンプトトークンの価格単位。" + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "プロンプトトークンの合計価格。" + }, + "completion_tokens": { + "type": "integer", + "description": "補完のトークン数。" + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "補完トークンあたりの単価。" + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "補完トークンの価格単位。" + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "補完トークンの合計価格。" + }, + "total_tokens": { + "type": "integer", + "description": "使用されたトークンの合計数。" + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "すべてのトークンの合計価格。" + }, + "currency": { + "type": "string", + "description": "課金通貨。" + }, + "latency": { + "type": "number", + "format": "double", + "description": "レイテンシ（秒）。" + } + } + }, + "RetrieverResource": { + "type": "object", + "description": "検索リソースの引用および帰属情報です。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "検索リソースの一意の ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "このリソースが属するメッセージの ID。" + }, + "position": { + "type": "integer", + "description": "リスト内のリソースの位置。" + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "ナレッジベース ID。" + }, + "dataset_name": { + "type": "string", + "description": "ナレッジベース名。" + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "ドキュメント ID。" + }, + "document_name": { + "type": "string", + "description": "ドキュメント名。" + }, + "data_source_type": { + "type": "string", + "description": "データソースのタイプ。" + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "ドキュメント内の特定のチャンクの ID。" + }, + "score": { + "type": "number", + "format": "float", + "description": "リソースの関連性スコア。" + }, + "hit_count": { + "type": "integer", + "description": "このチャンクがヒットした回数。" + }, + "word_count": { + "type": "integer", + "description": "チャンクの単語数。" + }, + "segment_position": { + "type": "integer", + "description": "ドキュメント内のチャンクの位置。" + }, + "index_node_hash": { + "type": "string", + "description": "インデックスノードのハッシュ。" + }, + "content": { + "type": "string", + "description": "リソースからのコンテンツスニペット。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "チャンクコンテンツの要約。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ（Unix エポック秒）。" + } + } + }, + "FileUploadResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "一意のファイル ID。" + }, + "name": { + "type": "string", + "description": "ファイル名。" + }, + "size": { + "type": "integer", + "description": "ファイルサイズ（バイト）。" + }, + "extension": { + "type": "string", + "nullable": true, + "description": "ファイル拡張子。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "ファイルの MIME タイプ。" + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ファイルをアップロードしたユーザーの ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "アップロードタイムスタンプ（Unix エポック秒）。" + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "ファイルのプレビュー URL。" + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "ファイルのソース URL。" + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "ファイルの元の URL。" + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられたユーザーの ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられたテナントの ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられた会話の ID。" + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "ファイルのストレージキー。" + } } }, - "MessageFeedbackRequestJa": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "アップボートは`like`、ダウンボートは`dislike`、アップボートの取り消しは`null`。" }, "user": { "type": "string", "description": "ユーザー識別子。" }, "content": { "type": "string", "nullable": true, "description": "メッセージのフィードバックです。" } } }, - "AppFeedbacksResponseJa": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemJa" }, "description": "このアプリの「いいね」とフィードバックの一覧を返します。" } } }, - "FeedbackItemJa": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "SuggestedQuestionsResponseJa": { "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "description": "推奨質問のリスト。" } } }, - "BasicConversationHistoryResponseJa": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返されたアイテムの数。" }, "has_more": { "type": "boolean", "description": "次のページがあるかどうか。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BasicConversationMessageItemJa" }, "description": "メッセージリスト。" } } }, - "BasicConversationMessageItemJa": { "type": "object", "description": "会話内の単一メッセージ。", "properties": { "id": { "type": "string", "format": "uuid", "description": "メッセージID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ユーザー入力パラメータ。" }, "query": { "type": "string", "description": "ユーザー入力/質問内容。" }, "answer": { "type": "string", "description": "応答メッセージ内容。" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItemJa" }, "description": "メッセージファイルリスト。" }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"], "description": "アップボートは`like` / ダウンボートは`dislike`。" } }, "description": "フィードバック情報。" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJa" }, "description": "引用と帰属リスト。" }, "agent_thoughts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentThoughtItemJa" }, "description": "エージェントの思考（基本アシスタントの場合は空）。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } }, - "AgentThoughtItemJa": { - "type": "object", "description": "エージェントの思考ステップ。", + "EndUserDetail": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "エージェント思考ID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, - "position": { "type": "integer", "description": "エージェント思考のメッセージ内での位置。" }, - "thought": { "type": "string", "nullable": true, "description": "LLMが考えていること。" }, - "observation": { "type": "string", "nullable": true, "description": "ツール呼び出しからの応答。" }, - "tool": { "type": "string", "nullable": true, "description": "呼び出されたツールのリスト、;で区切られます。" }, - "tool_input": { "type": "string", "nullable": true, "description": "ツールの入力、JSON形式。" }, - "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" }, - "message_files": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "ファイルID" }, "description": "現在のエージェント思考に関連するファイルIDのリスト。" } + "id": { + "type": "string", + "format": "uuid", + "description": "エンドユーザー ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "テナント ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "アプリケーション ID。" + }, + "type": { + "type": "string", + "description": "エンドユーザーのタイプ。Service API ユーザーの場合は常に `service_api` です。" + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "API リクエストで提供された `user` 識別子です（例：[チャットメッセージを送信](/api-reference/チャットメッセージ/チャットメッセージを送信) の `user` フィールド）。" + }, + "name": { + "type": "string", + "nullable": true, + "description": "エンドユーザー名。" + }, + "is_anonymous": { + "type": "boolean", + "description": "ユーザーが匿名かどうかを示します。元の API リクエストで `user` 識別子が提供されなかった場合、`true` になります。" + }, + "session_id": { + "type": "string", + "description": "セッション識別子。デフォルトは `external_user_id` の値です。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最終更新タイムスタンプ。" + } } }, - "MessageFileItemJa": { "type": "object", "description": "メッセージ内のファイル項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "ファイルタイプ、例：'image'。" }, "url": { "type": "string", "format": "url", "description": "プレビュー画像URL。" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "所属。" } } }, - "ConversationsListResponseJa": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返されたエントリの数。" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItemJa" }, "description": "会話のリスト。" } } }, - "ConversationListItemJa": { "type": "object", "description": "会話リスト内の単一項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "会話ID。" }, "name": { "type": "string", "description": "会話名。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ユーザー入力パラメータ。" }, "status": { "type": "string", "description": "会話状態。" }, "introduction": { "type": "string", "nullable": true, "description": "紹介。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" }, "updated_at": { "type": "integer", "format": "int64", "description": "更新タイムスタンプ。" } } }, - "ConversationRenameRequestJa": { "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true, "description": "(Optional)会話の名前。`auto_generate`が`true`の場合、省略できます。" }, "auto_generate": { "type": "boolean", "default": false, "description": "(Optional)タイトルを自動生成します。デフォルトは`false`です。" }, "user": { "type": "string", "description": "ユーザー識別子。" } } }, - "ConversationRenameResponseJa": { "$ref": "#/components/schemas/ConversationListItemJa" }, - "ConversationVariablesResponseJa": { "type": "object", "properties": { "limit": { "type": "integer", "description": "ページごとのアイテム数。" }, "has_more": { "type": "boolean", "description": "さらにアイテムがあるかどうか。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItemJa" }, "description": "変数のリスト。" } } }, - "ConversationVariableItemJa": { "type": "object", "description": "会話内の変数項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "変数ID。" }, "name": { "type": "string", "description": "変数名。" }, "value_type": { "type": "string", "description": "変数タイプ（文字列、数値、真偽値など）。" }, "value": { "type": "string", "description": "変数値。" }, "description": { "type": "string", "nullable": true, "description": "変数の説明。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最終更新タイムスタンプ。" } } }, - "AudioToTextRequestJa": { "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "オーディオファイル。サポートされている形式：`['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']`。ファイルサイズ制限：15MB。" }, "user": { "type": "string", "description": "ユーザー識別子。" } } }, - "AudioToTextResponseJa": { "type": "object", "properties": { "text": { "type": "string", "description": "出力テキスト。" } } }, - "TextToAudioFormRequestJa": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "メッセージID（優先）。" }, "text": { "type": "string", "description": "音声生成コンテンツ。" }, "user": { "type": "string", "description": "ユーザー識別子。" } }, "description": "`user`が必要です。`message_id`または`text`を提供してください。このバージョンはmultipart/form-dataです。" }, - "AppInfoResponseJa": { "type": "object", "description": "アプリケーションの基本情報。", "properties": { "name": { "type": "string", "description": "アプリケーションの名前。" }, "description": { "type": "string", "description": "アプリケーションの説明。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "アプリケーションのタグ。" } } }, - "BasicChatAppParametersResponseJa": { "type": "object", "description": "アプリケーションのパラメータ情報。", "properties": { "opening_statement": { "type": "string", "description": "開始文。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "開始時の推奨質問のリスト。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "答えを有効にした後の質問を提案します。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "音声からテキストへ。" }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" }, "voice": { "type": "string", "description": "音声タイプ。" }, "language": { "type": "string", "description": "言語。" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"], "description": "自動再生：enabled 有効, disabled 無効。" } }, "description": "テキストから音声へ。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "引用と帰属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "注釈返信。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemJa" }, "description": "ユーザー入力フォームの構成。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "画像設定。サポートされている画像タイプ：`png`, `jpg`, `jpeg`, `webp`, `gif`。" } }, "description": "ファイルアップロード構成。" }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer", "description": "ドキュメントアップロードサイズ制限（MB）。" }, "image_file_size_limit": { "type": "integer", "description": "画像ファイルアップロードサイズ制限（MB）。" }, "audio_file_size_limit": { "type": "integer", "description": "オーディオファイルアップロードサイズ制限（MB）。" }, "video_file_size_limit": { "type": "integer", "description": "ビデオファイルアップロードサイズ制限（MB）。" } }, "description": "システムパラメータ。" } } }, - "UserInputFormItemJa": { "type": "object", "description": "ユーザー入力フォーム内のコントロール項目。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperJa" }, { "$ref": "#/components/schemas/ParagraphControlWrapperJa" }, { "$ref": "#/components/schemas/SelectControlWrapperJa" } ] }, - "TextInputControlWrapperJa": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlJa" } }, "required":["text-input"] }, - "ParagraphControlWrapperJa": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlJa" } }, "required":["paragraph"] }, - "SelectControlWrapperJa": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlJa" } }, "required":["select"] }, - "TextInputControlJa": { "type": "object", "description": "テキスト入力コントロール。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" } } }, - "ParagraphControlJa": { "type": "object", "description": "段落テキスト入力コントロール。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" } } }, - "SelectControlJa": { "type": "object", "description": "ドロップダウンコントロール。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "オプション値。" } } }, - "AppMetaResponseJa": { "type": "object", "description": "アプリケーションのメタ情報。", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url", "description": "アイコンのURL。" }, { "$ref": "#/components/schemas/ToolIconDetailJa" } ] }, "description": "ツールアイコン。キーはツール名です。" } } }, - "ToolIconDetailJa": { "type": "object", "description": "ツールアイコンの詳細。", "properties": { "background": { "type": "string", "description": "背景色（16進数形式）。" }, "content": { "type": "string", "description": "絵文字。" } } }, - "WebAppSettingsResponseJa": { "type": "object", "description": "アプリのWebApp設定。", "properties": { "title": { "type": "string", "description": "WebApp名。" }, "chat_color_theme": { "type": "string", "description": "チャットの色テーマ、16進数形式。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "チャットの色テーマを反転するかどうか。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "アイコンタイプ。" }, "icon": { "type": "string", "description": "アイコン内容（絵文字または画像URL）。" }, "icon_background": { "type": "string", "description": "16進数形式の背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "アイコンのURL。" }, "description": { "type": "string", "description": "説明。" }, "copyright": { "type": "string", "description": "著作権情報。" }, "privacy_policy": { "type": "string", "description": "プライバシーポリシーのリンク。" }, "custom_disclaimer": { "type": "string", "description": "カスタム免責事項。" }, "default_language": { "type": "string", "description": "デフォルト言語。" }, "show_workflow_steps": { "type": "boolean", "description": "ワークフローの詳細を表示するかどうか。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "WebAppのアイコンをチャット内の🤖に置き換えるかどうか。" } } }, - "ErrorResponseJa": { "type": "object", "description": "エラー応答。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTPステータスコード。" }, "code": { "type": "string", "nullable": true, "description": "エラーコード。" }, "message": { "type": "string", "description": "エラーメッセージ。" } } } + "MessageFeedbackRequest": { + "type": "object", + "description": "メッセージフィードバックを送信するためのリクエストボディ。", + "required": [ + "user" + ], + "properties": { + "rating": { + "type": "string", + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "フィードバック評価。以前送信したフィードバックを取り消すには `null` に設定します。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。開発者が定義し、アプリケーション内での一意性を確保する必要があります。" + }, + "content": { + "type": "string", + "description": "追加の詳細を提供する任意のテキストフィードバック。" + } + } + }, + "AppFeedbacksResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "フィードバック項目のリスト。", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } + } + } + }, + "FeedbackItem": { + "type": "object", + "description": "単一のフィードバック項目。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "フィードバック ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "アプリケーション ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "メッセージ ID。" + }, + "rating": { + "type": "string", + "description": "フィードバック評価。肯定的な場合は `like`、否定的な場合は `dislike`。" + }, + "content": { + "type": "string", + "nullable": true, + "description": "任意のテキストフィードバック。" + }, + "from_source": { + "type": "string", + "description": "フィードバックのソース。API 経由でエンドユーザーが送信したフィードバックの場合は `user`、コンソールから送信されたフィードバックの場合は `admin`。" + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "フィードバックを送信したエンドユーザー ID。`from_source` が `user` の場合に存在します。" + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "フィードバックを送信したアカウント ID。`from_source` が `admin` の場合に存在します。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最終更新タイムスタンプ。" + } + } + }, + "SuggestedQuestionsResponse": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "結果ステータス。" + }, + "data": { + "type": "array", + "items": { + "type": "string" + }, + "description": "提案された質問のリストです。" + } + } + }, + "ConversationHistoryResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "has_more": { + "type": "boolean", + "description": "さらにメッセージがあるかどうかです。" + }, + "data": { + "type": "array", + "description": "メッセージのリストです。", + "items": { + "$ref": "#/components/schemas/ConversationMessageItem" + } + } + } + }, + "ConversationMessageItem": { + "type": "object", + "description": "会話内の単一メッセージです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "メッセージ ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "parent_message_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "スレッド会話の親メッセージ ID です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "このメッセージの入力変数です。" + }, + "query": { + "type": "string", + "description": "ユーザークエリテキストです。" + }, + "answer": { + "type": "string", + "description": "アシスタントの回答テキストです。" + }, + "status": { + "type": "string", + "description": "メッセージステータスです。成功したメッセージの場合は `normal`、生成に失敗した場合は `error` です。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "`status` が `error` の場合のエラーメッセージです。" + }, + "message_files": { + "type": "array", + "description": "このメッセージに添付されたファイルです。", + "items": { + "$ref": "#/components/schemas/MessageFileItem" + } + }, + "feedback": { + "type": "object", + "nullable": true, + "description": "このメッセージのユーザーフィードバックです。", + "properties": { + "rating": { + "type": "string", + "description": "フィードバック評価。肯定的な場合は `like`、否定的な場合は `dislike`。" + } + } + }, + "retriever_resources": { + "type": "array", + "description": "このメッセージに使用された検索リソースです。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + }, + "agent_thoughts": { + "type": "array", + "description": "このメッセージのエージェント思考です。", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ（Unix エポック秒）。" + }, + "extra_contents": { + "type": "array", + "description": "このメッセージに関連する追加の実行コンテンツです（人的介入フォームデータなど）。", + "items": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "MessageFileItem": { + "type": "object", + "description": "メッセージに添付されたファイルです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "元のファイル名です。" + }, + "type": { + "type": "string", + "description": "ファイルの種類（例: `image`）です。" + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "ファイルのプレビュー URL。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "ファイルの MIME タイプ。" + }, + "size": { + "type": "integer", + "nullable": true, + "description": "ファイルサイズ（バイト）。" + }, + "transfer_method": { + "type": "string", + "description": "使用された転送方法です。`remote_url` は URL ベースのファイル、`local_file` はアップロード済みファイル、`tool_file` はツール生成ファイルを示します。" + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "このファイルの所有者です。ユーザーがアップロードしたファイルの場合は `user`、アシスタントが生成したファイルの場合は `assistant` です。" + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "`local_file` で転送された場合のアップロードファイル ID です。" + } + } + }, + "AgentThoughtItem": { + "type": "object", + "description": "メッセージ内のエージェント思考ステップです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "エージェント思考 ID です。" + }, + "chain_id": { + "type": "string", + "nullable": true, + "description": "この思考のチェーン ID です。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "この思考が属する一意のメッセージ ID です。" + }, + "position": { + "type": "integer", + "description": "この思考の位置です。" + }, + "thought": { + "type": "string", + "description": "LLM が思考している内容です。" + }, + "tool": { + "type": "string", + "description": "呼び出されたツール（`;` で区切り）です。" + }, + "tool_labels": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "使用されたツールのラベルです。" + }, + "tool_input": { + "type": "string", + "description": "ツールの入力（JSON 形式）です。" + }, + "observation": { + "type": "string", + "description": "ツール呼び出しからのレスポンスです。" + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "この思考に関連するファイル ID です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + } + } + }, + "ConversationsListResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "has_more": { + "type": "boolean", + "description": "さらに会話があるかどうかです。" + }, + "data": { + "type": "array", + "description": "会話のリストです。", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } + } + } + }, + "ConversationListItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "name": { + "type": "string", + "description": "会話名です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "会話の入力変数です。" + }, + "status": { + "type": "string", + "description": "会話ステータスです。アクティブな会話の場合は `normal` です。" + }, + "introduction": { + "type": "string", + "description": "会話の紹介文です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最終更新タイムスタンプ。" + } + } + }, + "ConversationRenameRequest": { + "type": "object", + "description": "会話の名前変更用リクエストボディです。", + "properties": { + "name": { + "type": "string", + "description": "会話の名前です。`auto_generate` が `false` の場合は必須です。" + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "会話名を自動生成します。`true` の場合、`name` フィールドは無視されます。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子です。" + } + } + }, + "ConversationVariablesResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "has_more": { + "type": "boolean", + "description": "次のページがあるかどうかです。" + }, + "data": { + "type": "array", + "description": "会話変数のリストです。", + "items": { + "$ref": "#/components/schemas/ConversationVariableItem" + } + } + } + }, + "ConversationVariableItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Variable ID." + }, + "name": { + "type": "string", + "description": "変数名です。" + }, + "value_type": { + "type": "string", + "description": "変数の値の型です。指定可能な値：`string`、`number`、`object`、`secret`、`file`、`boolean`、`array[any]`、`array[string]`、`array[number]`、`array[object]`、`array[file]`、`array[boolean]`。" + }, + "value": { + "type": "string", + "description": "変数値（複雑な型の場合は JSON 文字列）。" + }, + "description": { + "type": "string", + "description": "変数の説明です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最終更新タイムスタンプ。" + } + } + }, + "ConversationVariableUpdateRequest": { + "type": "object", + "description": "会話変数を更新するためのリクエストボディです。", + "required": [ + "value" + ], + "properties": { + "value": { + "description": "変数の新しい値。変数の期待される型と一致する必要があります。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "音声からテキストへの変換のリクエストボディ。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音声ファイルです。対応形式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。上限：`30 MB`。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "音声認識からの出力テキスト。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "テキストから音声への変換のリクエストボディ。`message_id` または `text` のいずれかを指定してください。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "メッセージ ID です。両方が指定された場合、`text` よりも優先されます。" + }, + "text": { + "type": "string", + "description": "変換する音声コンテンツ。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + }, + "voice": { + "type": "string", + "description": "テキスト読み上げに使用する音声。利用可能な音声は、このアプリに設定された TTS プロバイダーによって異なります。デフォルトには[アプリケーションのパラメータ情報を取得](/api-reference/アプリケーション設定/アプリケーションのパラメータ情報を取得) → `text_to_speech.voice` の `voice` 値を使用してください。" + }, + "streaming": { + "type": "boolean", + "description": "ストリーミングレスポンスを有効にするかどうか。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "アプリケーション名。" + }, + "description": { + "type": "string", + "description": "アプリケーションの説明。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "アプリケーションタグ。" + }, + "mode": { + "type": "string", + "description": "アプリケーションモードです。`chat` は基本チャットアプリ、`agent-chat` はエージェントベースのアプリ、`advanced-chat` は chatflow アプリを示します。" + }, + "author_name": { + "type": "string", + "description": "アプリケーション作成者の名前。" + } + } + }, + "ChatAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "会話開始時に表示されるオープニングメッセージです。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "推奨される初期質問のリスト。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答後の推奨質問の設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "音声からテキストへの変換設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "テキストから音声への変換設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + }, + "voice": { + "type": "string", + "description": "TTS の音声識別子。" + }, + "language": { + "type": "string", + "description": "TTS の言語。" + }, + "autoPlay": { + "type": "string", + "description": "自動再生設定です。音声を自動再生するには `enabled`、手動再生を要求するには `disabled` を指定します。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "検索リソースの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "アノテーション返信の設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "類似コンテンツの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "センシティブワードフィルタリングの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "user_input_form": { + "type": "array", + "description": "ユーザー入力フォーム要素のリスト。", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "ファイルアップロードの設定。", + "properties": { + "image": { + "type": "object", + "description": "画像アップロードの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "画像アップロードが有効かどうか。" + }, + "number_limits": { + "type": "integer", + "description": "最大画像数。" + }, + "detail": { + "type": "string", + "description": "画像の詳細レベル。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "許可された転送方法。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "システムレベルのパラメータと制限。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "最大ファイルサイズ（MB）。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最大画像ファイルサイズ（MB）。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最大音声ファイルサイズ（MB）。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最大動画ファイルサイズ（MB）。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "ワークフローファイルアップロードの最大ファイル数。" + } + } + } + } + }, + "UserInputFormItem": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } + ] + }, + "TextInputControlWrapper": { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } + }, + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } + }, + "SelectControlWrapper": { + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } + }, + "TextInputControl": { + "type": "object", + "description": "テキスト入力フォームコントロールです。", + "properties": { + "label": { + "type": "string", + "description": "表示ラベルです。" + }, + "variable": { + "type": "string", + "description": "変数名です。" + }, + "required": { + "type": "boolean", + "description": "入力が必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルト値です。" + } + } + }, + "ParagraphControl": { + "type": "object", + "description": "段落（複数行テキスト）フォームコントロールです。", + "properties": { + "label": { + "type": "string", + "description": "表示ラベルです。" + }, + "variable": { + "type": "string", + "description": "変数名です。" + }, + "required": { + "type": "boolean", + "description": "入力が必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルト値です。" + } + } + }, + "SelectControl": { + "type": "object", + "description": "セレクト（ドロップダウン）フォームコントロールです。", + "properties": { + "label": { + "type": "string", + "description": "表示ラベルです。" + }, + "variable": { + "type": "string", + "description": "変数名です。" + }, + "required": { + "type": "boolean", + "description": "選択が必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルトで選択される値。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "このフォームコントロールの選択可能な値のリスト。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "アイコンの URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "ツールアイコン。キーはツール名です。" + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "絵文字を使用したツールアイコンの詳細。", + "properties": { + "background": { + "type": "string", + "description": "16進数形式の背景色。" + }, + "content": { + "type": "string", + "description": "Emoji コンテンツ。" + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp タイトル。" + }, + "chat_color_theme": { + "type": "string", + "description": "チャットカラーテーマ。" + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "チャットカラーテーマが反転しているかどうか。" + }, + "icon_type": { + "type": "string", + "description": "使用されるアイコンのタイプ。`emoji` は絵文字アイコン、`image` はアップロードされた画像アイコンです。" + }, + "icon": { + "type": "string", + "description": "アイコンのコンテンツ（絵文字または画像 ID）。" + }, + "icon_background": { + "type": "string", + "description": "アイコンの背景色。" + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "アイコン画像の URL。" + }, + "description": { + "type": "string", + "description": "WebApp の説明。" + }, + "copyright": { + "type": "string", + "description": "著作権テキスト。" + }, + "privacy_policy": { + "type": "string", + "description": "プライバシーポリシー URL。" + }, + "custom_disclaimer": { + "type": "string", + "description": "カスタム免責事項テキスト。" + }, + "default_language": { + "type": "string", + "description": "デフォルト言語コード。" + }, + "show_workflow_steps": { + "type": "boolean", + "description": "ワークフローステップを表示するかどうか。" + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "アプリアイコンを回答アイコンとして使用するかどうか。" + } + } + }, + "AnnotationListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "description": "現在のページのアノテーション項目のリストです。" + }, + "has_more": { + "type": "boolean", + "description": "現在の結果セットの後にさらにページがある場合は `true` です。" + }, + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "クエリに一致するアノテーションの合計数です。" + }, + "page": { + "type": "integer", + "description": "現在のページ番号です。" + } + } + }, + "AnnotationItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "アノテーションの一意識別子です。" + }, + "question": { + "type": "string", + "nullable": true, + "description": "このアノテーションをトリガーする質問テキストです。" + }, + "answer": { + "type": "string", + "nullable": true, + "description": "アノテーションがマッチした際に返される定義済みの回答です。" + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "このアノテーションがマッチして返信として返された回数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "作成タイムスタンプ（Unix エポック秒）。" + } + } + }, + "CreateAnnotationRequest": { + "type": "object", + "description": "新しいアノテーションを作成するためのリクエストボディです。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "アノテーションの質問です。" + }, + "answer": { + "type": "string", + "description": "アノテーションの回答です。" + } + } + }, + "UpdateAnnotationRequest": { + "type": "object", + "description": "アノテーション更新のリクエストボディです。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "更新されたアノテーションの質問です。" + }, + "answer": { + "type": "string", + "description": "更新されたアノテーションの回答です。" + } + } + }, + "InitialAnnotationReplySettingsRequest": { + "type": "object", + "description": "アノテーション返信設定を構成するためのリクエストボディです。", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], + "properties": { + "embedding_provider_name": { + "type": "string", + "description": "埋め込みモデルプロバイダーの名前（例：`openai`、`cohere`）です。" + }, + "embedding_model_name": { + "type": "string", + "description": "アノテーションマッチングに使用する埋め込みモデルの名前です（例：`text-embedding-3-small`）。" + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "アノテーションがマッチとみなされるための最低類似度スコアです。値が高いほど、より正確なマッチが必要になります。", + "minimum": 0, + "maximum": 1 + } + } + }, + "InitialAnnotationReplySettingsResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "非同期ジョブ ID です。[アノテーション返信の初期設定タスクステータスを取得](/api-reference/アノテーション管理/アノテーション返信の初期設定タスクステータスを取得) と組み合わせて進捗を追跡します。" + }, + "job_status": { + "type": "string", + "description": "現在のジョブステータスです。`waiting` はキュー待ち、`processing` は処理中、`completed` は完了、`error` は失敗を示します。" + } + } + }, + "InitialAnnotationReplySettingsStatusResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "[アノテーション返信を設定](/api-reference/アノテーション管理/アノテーション返信を設定) 呼び出しから取得したジョブ ID です。" + }, + "job_status": { + "type": "string", + "description": "現在のジョブステータスです。`waiting` はキュー待ち、`processing` は処理中、`completed` は完了、`error` は失敗を示します。" + }, + "error_msg": { + "type": "string", + "description": "ジョブが失敗した理由を説明するエラーメッセージです。`job_status` が `error` でない場合は空文字列です。" + } + } + } } }, "tags": [ - { "name": "チャットメッセージ", "description": "チャットメッセージと対話に関連する操作。" }, - { "name": "ファイル操作", "description": "ファイルアップロードとプレビューに関連する操作。" }, - { "name": "エンドユーザー", "description": "エンドユーザー情報に関連する操作。" }, - { "name": "メッセージフィードバック", "description": "ユーザーからのメッセージフィードバック操作。" }, - { "name": "会話管理", "description": "会話セッションの管理に関連する操作。" }, - { "name": "音声とテキスト変換", "description": "テキストから音声、音声からテキストへの変換操作。" }, - { "name": "アプリケーション設定", "description": "アプリケーション設定と情報の取得に関連する操作。" } + { + "name": "チャットメッセージ", + "description": "チャットメッセージとインタラクションに関連する操作です。" + }, + { + "name": "ファイル操作", + "description": "ファイルのアップロードとプレビューの操作です。" + }, + { + "name": "エンドユーザー", + "description": "エンドユーザー情報に関連する操作です。" + }, + { + "name": "メッセージフィードバック", + "description": "ユーザーフィードバックの操作です。" + }, + { + "name": "会話管理", + "description": "会話管理に関連する操作です。" + }, + { + "name": "音声・テキスト変換", + "description": "テキスト読み上げと音声認識の操作です。" + }, + { + "name": "アプリケーション設定", + "description": "アプリケーション設定と情報を取得する操作です。" + }, + { + "name": "アノテーション管理", + "description": "ダイレクト返信用のアノテーション管理に関連する操作です。" + } ] -} \ No newline at end of file +} diff --git a/ja/api-reference/openapi_chatflow.json b/ja/api-reference/openapi_chatflow.json index eb6d6070..0a792b88 100644 --- a/ja/api-reference/openapi_chatflow.json +++ b/ja/api-reference/openapi_chatflow.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "高度なチャットアプリAPI (Chatflow API)", - "description": "チャットアプリケーションはセッションの持続性をサポートしており、以前のチャット履歴を応答のコンテキストとして使用できます。これは、チャットボットやカスタマーサービスAIなどに適用できます。", + "description": "Chatflow アプリケーションはセッションの永続化をサポートし、過去のチャット履歴をレスポンスのコンテキストとして使用できます。Chatflow アプリは `advanced-chat` モードを使用し、ノードの開始・完了、イテレーション、ワークフローのライフサイクルを含む詳細な実行追跡のためのワークフローレベルのストリーミングイベントを提供します。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "APIのベースURL。 {api_base_url} をアプリケーション提供の実際のAPIベースURLに置き換えてください。", + "description": "Chatflow アプリ API のベース URL です。{api_base_url} をアプリケーションに提供された実際の API ベース URL に置き換えてください。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "実際のAPIベースURL" + "description": "API の実際のベース URL" } } } @@ -28,25 +28,27 @@ "summary": "チャットメッセージを送信", "description": "チャットアプリケーションにリクエストを送信します。", "operationId": "sendChatflowMessageJp", - "tags": ["チャットメッセージ"], + "tags": [ + "チャットメッセージ" + ], "requestBody": { - "description": "チャットメッセージ送信のリクエストボディ。", + "description": "チャットメッセージを送信するためのリクエストボディ。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatflowRequestJp" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file": { - "summary": "ファイルとカスタム入力を含むストリーミングリクエストの例", + "streaming_example": { + "summary": "リクエスト例 - ストリーミングモード", "value": { "inputs": { - "name": "dify" + "city": "San Francisco" }, - "query": "iPhone 13 Pro Maxの仕様は何ですか？", + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276", + "conversation_id": "", "user": "abc-123", "files": [ { @@ -56,57 +58,15 @@ } ] } - } - } - } - } - }, - "responses": { - "200": { - "description": "リクエスト成功。応答のコンテントタイプと構造はリクエストの `response_mode` パラメータに依存します。\n- `response_mode` が `blocking` の場合、`application/json` 形式の `ChatCompletionResponseJp` オブジェクトを返します。\n- `response_mode` が `streaming` の場合、`text/event-stream` 形式の `ChunkChatflowEventJp` オブジェクトのストリームを返します。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChatCompletionResponseJp" - } - }, - "text/event-stream": { - "schema": { - "type": "string", - "description": "SSEイベントストリーム。各イベントは 'data: ' で始まり、'\\n\\n' で終わります。詳細な構造は `ChunkChatflowEventJp` を参照してください。" - } - } - } - }, - "400": { "$ref": "#/components/responses/BadRequestGenericJp" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } - } - } - }, - "/files/upload": { - "post": { - "summary": "ファイルアップロード", - "description": "メッセージ送信時に使用するファイルをアップロードし、画像とテキストのマルチモーダル理解を可能にします。アプリケーションでサポートされている形式をサポートします。アップロードされたファイルは現在のエンドユーザーのみが使用できます。", - "operationId": "uploadChatflowFileJp", - "tags": ["ファイル操作"], - "requestBody": { - "description": "ファイルアップロードリクエスト。`multipart/form-data` リクエストが必要です。", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "アップロードするファイル。" - }, - "user": { - "type": "string", - "description": "ユーザー識別子。開発者のルールによって定義され、アプリケーション内で一意でなければなりません。**重要な注意事項**: Service API は WebApp で作成された対話を共有しません。API を通じて作成された対話は、WebApp インターフェースで作成されたものとは分離されています。" + }, + "blocking_example": { + "summary": "リクエスト例 - ブロッキングモード", + "value": { + "inputs": {}, + "query": "What are the specs of the iPhone 13 Pro Max?", + "response_mode": "blocking", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "user": "abc-123" } } } @@ -115,183 +75,219 @@ }, "responses": { "200": { - "description": "ファイルアップロード成功。", + "description": "リクエスト成功。コンテンツタイプと構造はリクエストの `response_mode` パラメータに依存します。\n\n- `response_mode` が `blocking` の場合、 `application/json` で `ChatCompletionResponse` オブジェクトを返します。\n- `response_mode` が `streaming` の場合、 `text/event-stream` で `ChunkChatEvent` オブジェクトのストリームを返します。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FileUploadResponseJp" + "$ref": "#/components/schemas/ChatCompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "レスポンス例 - ブロッキングモード", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "advanced-chat", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + } } - } - } - }, - "201": { - "description": "ファイル作成成功（代替成功コード）。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } - }, - "400": { "$ref": "#/components/responses/BadRequestFileJp" }, - "413": { "$ref": "#/components/responses/FileTooLargeJp" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileJp" }, - "503": { "$ref": "#/components/responses/S3ErrorFileJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "エンドユーザー取得", - "description": "IDでエンドユーザーを取得します。\n\n他のAPIがエンドユーザーID（例：ファイルアップロードの `created_by`）を返す場合に利用できます。", - "operationId": "getEndUserChatflowJp", - "tags": ["エンドユーザー"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "エンドユーザーID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "responses": { - "200": { - "description": "エンドユーザーの取得に成功しました。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailJp" } - } - } - }, - "404": { "$ref": "#/components/responses/EndUserNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } - } - } - }, - "/files/{file_id}/preview": { - "get": { - "summary": "ファイルプレビュー", - "description": "アップロードされたファイルのプレビューまたはダウンロード。このエンドポイントは、ファイルアップロードAPIを通じて事前にアップロードされたファイルにアクセスすることができます。ファイルは、リクエストしているアプリケーション内のメッセージに属している場合のみアクセス可能です。", - "operationId": "previewChatflowFileJp", - "tags": ["ファイル操作"], - "parameters": [ - { - "name": "file_id", - "in": "path", - "required": true, - "description": "プレビューするファイルの一意識別子、ファイルアップロードAPIのレスポンスから取得されます。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "as_attachment", - "in": "query", - "required": false, - "description": "ファイルを添付ファイルとして強制ダウンロードするかどうか。デフォルトは`false`（ブラウザでプレビュー）です。", - "schema": { - "type": "boolean", - "default": false - } - } - ], - "responses": { - "200": { - "description": "ファイルコンテンツが正常に返されました。ヘッダーはファイルタイプとリクエストパラメータに基づいて設定されます。", - "content": { - "image/png": { + }, + "text/event-stream": { "schema": { "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - }, - "headers": { - "Content-Type": { - "description": "ファイルのMIMEタイプ", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "ファイルサイズ（バイト単位、利用可能な場合）", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "as_attachment=trueの場合、'attachment'に設定されます", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "パフォーマンス用キャッシュヘッダー", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "オーディオ/ビデオファイルの場合は'bytes'に設定されます", - "schema": { - "type": "string", - "example": "bytes" + "description": "サーバー送信イベント (SSE) のストリームです。各イベントは `data: ` プレフィックス付きの JSON オブジェクトで、2 つの改行で終了します。\n\n**SSE パースガイド：**各イベントは `data: ` プレフィックス付きの JSON オブジェクトの行で、`\\n\\n` で終了します。JSON をパースする前に `data: ` プレフィックスを除去してください。JSON 内の `event` フィールドがイベントタイプを決定します。終了イベント（`message_end`、`workflow_finished`、`error` など）を受信するとストリームは終了します。`ping` イベント（10 秒ごとに接続維持のために送信）は無視してください。ストリーム内でエラーイベントが発生しても HTTP ステータスコードは常に `200` です。" + }, + "examples": { + "streamingResponseBasic": { + "summary": "Response Example - Streaming (Basic)", + "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" + }, + "streamingResponseWorkflow": { + "summary": "Response Example - Streaming (Workflow)", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}" + } } } } }, "400": { - "description": "不正なリクエスト。可能なエラーコード:\n- `invalid_param`: 異常なパラメータ入力。", + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルは利用できません。\n- `completion_request_error` : テキスト生成に失敗しました。\n- `bad_request` : Cannot use draft workflow version.\n- `bad_request` : Invalid `workflow_id` format.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } - } - } - }, - "403": { - "description": "禁止。可能なエラーコード:\n- `file_access_denied`: ファイルアクセス拒否またはファイルが現在のアプリケーションに属していません。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "conversation_completed": { + "summary": "conversation_completed", + "value": { + "status": 400, + "code": "conversation_completed", + "message": "The conversation has ended. Please start a new conversation." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "is_draft_workflow": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. " + } + }, + "workflow_id_format_error": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Invalid workflow_id format: 'not-a-valid-id'. " + } + } + } } } }, "404": { - "description": "見つかりません。可能なエラーコード:\n- `file_not_found`: ファイルが見つからないか削除されています。", + "description": "- `not_found` : 会話が存在しません。\n- `not_found` : 指定された `workflow_id` のワークフローが見つかりません。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "workflow_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab" + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : このアプリケーションへの同時リクエストが多すぎます。\n- `rate_limit_error` : アップストリームのモデルプロバイダーのレート制限を超えました。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } } } }, "500": { - "description": "内部サーバーエラー。", + "description": "`internal_server_error` : 内部サーバーエラー。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -301,16 +297,20 @@ "/chat-messages/{task_id}/stop": { "post": { "summary": "生成を停止", - "description": "チャットメッセージの生成を停止します。ストリーミングモードでのみサポートされています。", + "description": "チャットメッセージ生成タスクを停止します。`streaming` モードでのみサポートされます。", "operationId": "stopChatflowMessageGenerationJp", - "tags": ["チャットメッセージ"], + "tags": [ + "チャットメッセージ" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "タスクID、ストリーミングチャンクの返り値から取得できます。", - "schema": { "type": "string", "format": "uuid" } + "description": "タスク ID です。[チャットメッセージを送信](/api-reference/チャットメッセージ/チャットメッセージを送信) API のストリーミングチャンクレスポンスから取得できます。", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -319,66 +319,45 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { "user": { "type": "string", - "description": "ユーザー識別子。送信メッセージインターフェースで渡されたユーザーと一致している必要があります。" + "description": "ユーザー識別子。メッセージ送信インターフェースで渡された user と一致する必要があります。" + } + } + }, + "examples": { + "example": { + "summary": "リクエスト例", + "value": { + "user": "abc-123" } } } } } }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResultJp" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "メッセージフィードバック", - "description": "エンドユーザーはフィードバックメッセージを提供でき、アプリケーション開発者が期待される出力を最適化するのを支援します。", - "operationId": "postChatflowMessageFeedbackJp", - "tags": ["メッセージフィードバック"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "メッセージID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestJp" } - } - } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResultJp" } - } - } - }, - "/app/feedbacks": { - "get": { - "summary": "アプリのメッセージの「いいね」とフィードバックを取得", - "description": "アプリのエンドユーザーからのフィードバックや「いいね」を取得します。", - "operationId": "getChatflowAppFeedbacksJp", - "tags": ["メッセージフィードバック"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParamJp" }, - { "$ref": "#/components/parameters/LimitQueryParamJp" } - ], "responses": { "200": { - "description": "アプリのフィードバックリストを正常に取得しました。", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseJp" } + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } } } } @@ -387,55 +366,548 @@ }, "/messages/{message_id}/suggested": { "get": { - "summary": "次の推奨質問", + "summary": "次の推奨質問を取得", "description": "現在のメッセージに対する次の質問の提案を取得します。", "operationId": "getChatflowSuggestedQuestionsJp", - "tags": ["チャットメッセージ"], + "tags": [ + "チャットメッセージ" + ], "parameters": [ { "name": "message_id", "in": "path", "required": true, - "description": "メッセージID。", - "schema": { "type": "string", "format": "uuid" } + "description": "メッセージ ID。", + "schema": { + "type": "string" + } }, - { "$ref": "#/components/parameters/UserQueryParamJp" } + { + "name": "user", + "in": "query", + "required": true, + "description": "ユーザー識別子。", + "schema": { + "type": "string" + } + } ], "responses": { "200": { - "description": "推奨質問リストを正常に取得しました。", + "description": "提案された質問の取得に成功しました。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponseJp" } + "schema": { + "$ref": "#/components/schemas/SuggestedQuestionsResponse" + }, + "examples": { + "suggestedQuestions": { + "summary": "レスポンス例", + "value": { + "result": "success", + "data": [ + "What colors does the iPhone 13 Pro Max come in?", + "How does the battery compare to iPhone 12?", + "What is the price range?" + ] + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : アプリモードが API ルートと一致しません。\n- `bad_request` : 推奨質問機能が無効です。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Suggested Questions Is Disabled." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : メッセージが存在しません。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } } } }, - "/messages": { - "get": { - "summary": "会話履歴メッセージを取得", - "description": "スクロールロード形式で履歴チャット記録を返し、最初のページは最新の`{limit}`メッセージを返します。つまり、逆順です。", - "operationId": "getChatflowConversationHistoryJp", - "tags": ["会話管理"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdQueryParamJp" }, - { "$ref": "#/components/parameters/UserQueryParamJp" }, - { - "name": "first_id", - "in": "query", - "description": "現在のページの最初のチャット記録のID、デフォルトはnullです。", - "schema": { "type": "string", "format": "uuid", "nullable": true } + "/files/upload": { + "post": { + "operationId": "uploadChatflowFileJp", + "tags": [ + "ファイル操作" + ], + "summary": "ファイルをアップロード", + "description": "メッセージ送信時に使用するファイルをアップロードします。画像、ドキュメント、音声、動画のマルチモーダル理解が可能です。アップロードされたファイルは現在のエンドユーザーのみが使用できます。", + "requestBody": { + "description": "ファイルアップロードリクエスト。multipart/form-data 形式が必要です。", + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "アップロードするファイル。サポートされるタイプには画像、ドキュメント、音声、動画が含まれます。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。開発者のルールで定義され、アプリケーション内で一意である必要があります。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "ファイルが正常にアップロードされました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Jp" } + "400": { + "description": "- `no_file_uploaded` : リクエストにファイルが提供されていません。\n- `too_many_files` : 1 回のリクエストにつき 1 ファイルのみ許可されています。\n- `filename_not_exists_error` : アップロードされたファイルにファイル名がありません。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : ファイルサイズの上限を超えています。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 許可されていないファイルタイプです。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { + "get": { + "operationId": "previewChatflowFileJp", + "tags": [ + "ファイル操作" + ], + "summary": "ファイルをダウンロード", + "description": "以前[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API 経由でアップロードされたファイルをプレビューまたはダウンロードします。ファイルは、リクエスト元のアプリケーション内のメッセージに属する場合のみアクセスできます。", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "プレビューするファイルの一意の識別子です。[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API のレスポンスから取得します。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "`true` の場合、ブラウザでプレビューする代わりにファイルを添付ファイルとして強制ダウンロードします。", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子。エンドユーザーのコンテキストに使用されます。", + "schema": { + "type": "string" + } + } ], "responses": { "200": { - "description": "会話履歴メッセージを正常に取得しました。", + "description": "生のファイルコンテンツを返します。`Content-Type` ヘッダーはファイルの MIME タイプに設定されます。`as_attachment` が `true` の場合、ファイルは `Content-Disposition: attachment` としてダウンロード形式で返されます。", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : リクエストされたファイルへのアクセスが拒否されました。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationHistoryResponseJp" } + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : リクエストされたファイルが見つかりません。", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "operationId": "getEndUserChatflowJp", + "tags": [ + "エンドユーザー" + ], + "summary": "エンドユーザー取得", + "description": "ID を指定してエンドユーザーを取得します。他の API がエンドユーザー ID を返す場合（例：[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード)の `created_by`）に便利です。", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "エンドユーザー ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "エンドユーザーを正常に取得しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "レスポンス例", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : エンドユーザーが見つかりません。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/messages/{message_id}/feedbacks": { + "post": { + "operationId": "postChatflowMessageFeedbackJp", + "tags": [ + "メッセージフィードバック" + ], + "summary": "メッセージフィードバックを送信", + "description": "メッセージに対するフィードバックを送信します。エンドユーザーはメッセージを `like` または `dislike` で評価でき、任意でテキストフィードバックを提供できます。`rating` に `null` を渡すと、以前送信したフィードバックを取り消せます。", + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "メッセージ ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "リクエスト例", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : メッセージが存在しません。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/app/feedbacks": { + "get": { + "operationId": "getChatflowAppFeedbacksJp", + "tags": [ + "メッセージフィードバック" + ], + "summary": "アプリのフィードバック一覧を取得", + "description": "このアプリケーションのメッセージに対して送信されたすべてのフィードバックのページネーション付きリストを取得します。エンドユーザーと管理者のフィードバックの両方が含まれます。", + "parameters": [ + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1ページあたりのレコード数。", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } + } + ], + "responses": { + "200": { + "description": "アプリケーションフィードバックのリスト。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "rating": "like", + "content": "The response accurately answered my question about product specifications.", + "from_source": "user", + "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "from_account_id": null, + "created_at": "2025-01-16T14:30:29Z", + "updated_at": "2025-01-16T14:30:29Z" + }, + { + "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", + "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", + "rating": "dislike", + "content": "The answer was too vague and did not address the specific pricing question.", + "from_source": "user", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", + "from_account_id": null, + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" + } + ] + } + } + } } } } @@ -444,22 +916,616 @@ }, "/conversations": { "get": { - "summary": "会話を取得", - "description": "現在のユーザーの会話リストを取得し、デフォルトで最新の20件を返します。", + "summary": "会話一覧を取得", + "description": "現在のユーザーの会話リストを、最近アクティブな順に取得します。", "operationId": "getChatflowConversationsListJp", - "tags": ["会話管理"], + "tags": [ + "会話管理" + ], "parameters": [ - { "$ref": "#/components/parameters/UserQueryParamJp" }, - { "$ref": "#/components/parameters/LastIdQueryParamJp" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Jp" }, - { "$ref": "#/components/parameters/SortByQueryParamJp" } + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子。", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "現在のページの最後のレコードの ID（ページネーション用）です。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "返すレコード数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "sort_by", + "in": "query", + "required": false, + "description": "ソートフィールドです。降順にするには '-' プレフィックスを使用します。", + "schema": { + "type": "string", + "enum": [ + "created_at", + "-created_at", + "updated_at", + "-updated_at" + ], + "default": "-updated_at" + } + } ], "responses": { "200": { - "description": "会話リストを正常に取得しました。", + "description": "会話リストの取得に成功しました。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationsListResponseJp" } + "schema": { + "$ref": "#/components/schemas/ConversationsListResponse" + }, + "examples": { + "conversationsList": { + "summary": "レスポンス例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 前の会話が存在しません（無効な `last_id`）。", + "content": { + "application/json": { + "examples": { + "last_conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Last Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/messages": { + "get": { + "summary": "会話履歴メッセージ一覧を取得", + "description": "スクロール読み込み形式で過去のチャット記録を返します。最初のページは最新の `limit` 件のメッセージを返します（時系列の逆順）。", + "operationId": "getChatflowConversationHistoryJp", + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子。", + "schema": { + "type": "string" + } + }, + { + "name": "first_id", + "in": "query", + "required": false, + "description": "現在のページの最初のチャット記録の ID です。デフォルトは `null`（最新のメッセージを取得）です。次のページを取得するには、現在のリストの最初のメッセージの ID を使用して、より古いメッセージを取得します。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "リクエストごとに返すチャット履歴メッセージの数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "会話履歴の取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "レスポンス例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "parent_message_id": null, + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "status": "normal", + "error": null, + "message_files": [], + "feedback": { + "rating": "like" + }, + "retriever_resources": [], + "agent_thoughts": [], + "created_at": 1705407629 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 会話が存在しません。\n- `not_found` : 最初のメッセージが存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "first_message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "First Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables": { + "get": { + "summary": "会話変数の取得", + "description": "特定の会話から変数を取得します。", + "operationId": "getChatflowConversationVariablesJp", + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子です。", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "現在のページの最後のレコードの ID（ページネーション用）です。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "返すレコード数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "variable_name", + "in": "query", + "required": false, + "description": "指定した名前で変数をフィルタリングします。", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + } + ], + "responses": { + "200": { + "description": "会話変数の取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariablesResponse" + }, + "examples": { + "conversationVariables": { + "summary": "レスポンス例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "dark_mode", + "description": "ユーザー設定", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会話が存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/name": { + "post": { + "summary": "会話の名前を変更", + "description": "会話の名前を変更するか、自動的に生成します。会話名は複数の会話をサポートするクライアントでの表示に使用されます。", + "operationId": "renameChatflowConversationJp", + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationRenameRequest" + }, + "examples": { + "renameExample": { + "summary": "リクエスト例", + "value": { + "name": "iPhone Specs Chat", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "会話が正常に名前変更されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationListItem" + }, + "examples": { + "renamedConversation": { + "summary": "レスポンス例", + "value": { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会話が存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables/{variable_id}": { + "put": { + "summary": "会話変数を更新", + "description": "特定の会話変数の値を更新します。値は期待される型と一致する必要があります。", + "operationId": "updateChatflowConversationVariableJa", + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "variable_id", + "in": "path", + "required": true, + "description": "Variable ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableUpdateRequest" + }, + "examples": { + "updateStringVariable": { + "summary": "リクエスト例", + "value": { + "value": "new value", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "変数が正常に更新されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableItem" + }, + "examples": { + "updatedVariable": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "new value", + "description": "ユーザー設定", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : アプリモードが API ルートと一致しません。\n- `bad_request` : 変数値の型が一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "type_mismatch": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Value type mismatch: expected string, got integer." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 会話が存在しません。\n- `not_found` : 会話変数が存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "variable_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Variable Not Exists." + } + } + } } } } @@ -469,314 +1535,4673 @@ "/conversations/{conversation_id}": { "delete": { "summary": "会話を削除", - "description": "指定された会話を削除します。", + "description": "会話を削除します。", "operationId": "deleteChatflowConversationJp", - "tags": ["会話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJp" } ], + "tags": [ + "会話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会話 ID。", + "schema": { + "type": "string" + } + } + ], "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { - "type": "object", "required": ["user"], - "properties": { "user": { "type": "string", "description": "ユーザー識別子。**重要な注意事項**: Service API は WebApp で作成された対話を共有しません。API を通じて作成された対話は、WebApp インターフェースで作成されたものとは分離されています。" } } + "type": "object", + "properties": { + "user": { + "type": "string", + "description": "ユーザー識別子です。" + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "リクエスト例" + } } } } }, - "responses": { "204": { "description": "会話が正常に削除されました。コンテンツはありません。" } } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "会話の名前を変更", - "description": "セッションの名前を変更します。", - "operationId": "renameChatflowConversationJp", - "tags": ["会話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJp" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequestJp" } } } - }, "responses": { - "200": { "description": "会話の名前が正常に変更されました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameResponseJp" } } } } - } - } - }, - "/conversations/{conversation_id}/variables": { - "get": { - "summary": "会話変数の取得", - "description": "特定の会話から変数を取得します。このエンドポイントは、会話中に取得された構造化データを抽出するのに役立ちます。", - "operationId": "getChatflowConversationVariablesJp", - "tags": ["会話管理"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParamJp" }, - { "$ref": "#/components/parameters/UserQueryParamJp" }, - { "$ref": "#/components/parameters/LastIdQueryParamJp" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Jp" } - ], - "responses": { - "200": { "description": "会話変数を正常に取得しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariablesResponseJp" } } } }, - "404": { "$ref": "#/components/responses/ConversationNotFoundJp" } + "204": { + "description": "会話の削除に成功しました。コンテンツは返されません。" + }, + "400": { + "description": "`not_chat_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会話が存在しません。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } } } }, "/audio-to-text": { "post": { - "summary": "音声からテキストへ", - "description": "オーディオファイルをテキストに変換します。サポートされている形式：mp3, mp4, mpeg, mpga, m4a, wav, webm。ファイルサイズ制限：15MB。", "operationId": "chatflowAudioToTextJp", - "tags": ["音声・テキスト変換"], + "tags": [ + "音声・テキスト変換" + ], + "summary": "音声をテキストに変換", + "description": "音声ファイルをテキストに変換します。サポートされる形式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファイルサイズの上限は `30 MB` です。", "requestBody": { "required": true, - "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequestJp" } } } + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } }, "responses": { - "200": { "description": "音声をテキストに正常に変換しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponseJp" } } } } + "200": { + "description": "音声からテキストへの変換に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "レスポンス例", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `no_audio_uploaded` : 音声ファイルがアップロードされていません。\n- `provider_not_support_speech_to_text` : モデルプロバイダーが音声認識をサポートしていません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルはこの操作をサポートしていません。\n- `completion_request_error` : 音声認識リクエストに失敗しました。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音声ファイルサイズが上限を超えています。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 許可されていない音声タイプです。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } } } }, "/text-to-audio": { "post": { - "summary": "テキストから音声へ", - "description": "テキストコンテンツを音声に変換します。", "operationId": "chatflowTextToAudioJp", - "tags": ["音声・テキスト変換"], + "tags": [ + "音声・テキスト変換" + ], + "summary": "テキストを音声に変換", + "description": "テキストを音声に変換します。", "requestBody": { "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToAudioJsonRequestJp" } } } + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "リクエスト例", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } }, "responses": { "200": { - "description": "音声ファイルを正常に生成しました。", - "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, - "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } + "description": "生成された音声ファイルを返します。`Content-Type` ヘッダーは音声の MIME タイプ（例：`audio/wav`、`audio/mp3`）に設定されます。`streaming` が `true` の場合、音声はチャンク転送エンコーディングでストリーミングされます。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルはこの操作をサポートしていません。\n- `completion_request_error` : テキスト読み上げリクエストに失敗しました。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } } } } }, "/info": { "get": { - "summary": "アプリケーションの基本情報を取得", "operationId": "getChatflowAppInfoJp", - "tags": ["アプリケーション設定"], - "responses": { "200": { "description": "アプリケーションの基本情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリケーションの基本情報を取得", + "description": "このアプリケーションの基本情報（名前、説明、タグ、モード）を取得します。", + "responses": { + "200": { + "description": "アプリケーションの基本情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "レスポンス例", + "value": { + "name": "My Chatflow App", + "description": "便利なカスタマーサービスチャットボット。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "advanced-chat", + "author_name": "Dify Team" + } + } + } + } + } + } + } } }, "/parameters": { "get": { - "summary": "アプリケーションのパラメータ情報を取得", - "description": "ページに入る際に、機能、入力パラメータ名、タイプ、デフォルト値などの情報を取得するために使用されます。", "operationId": "getChatflowAppParametersJp", - "tags": ["アプリケーション設定"], - "responses": { "200": { "description": "アプリケーションのパラメータ情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAppParametersResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリケーションのパラメータ情報を取得", + "description": "アプリケーションの入力フォーム設定（機能スイッチ、入力パラメータ名、タイプ、デフォルト値）を取得します。", + "responses": { + "200": { + "description": "アプリケーションパラメータ情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "レスポンス例", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } } }, "/meta": { "get": { - "summary": "アプリケーションのメタ情報を取得", - "description": "このアプリケーションのツールのアイコンを取得するために使用されます。", "operationId": "getChatflowAppMetaJp", - "tags": ["アプリケーション設定"], - "responses": { "200": { "description": "アプリケーションのメタ情報を正常に取得しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリケーションのメタ情報を取得", + "description": "このアプリケーションのメタデータ（ツールアイコンやその他の設定詳細）を取得します。", + "responses": { + "200": { + "description": "アプリケーションのメタ情報を正常に取得しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "レスポンス例", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } } }, "/site": { "get": { - "summary": "アプリのWebApp設定を取得", - "description": "アプリのWebApp設定を取得するために使用します。", "operationId": "getChatflowWebAppSettingsJp", - "tags": ["アプリケーション設定"], - "responses": { "200": { "description": "WebAppの設定情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリの WebApp 設定を取得", + "description": "このアプリケーションの WebApp 設定（サイト設定、テーマ、カスタマイズオプション）を取得します。", + "responses": { + "200": { + "description": "アプリケーションの WebApp 設定。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "レスポンス例", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "便利なカスタマーサービスチャットボット。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このアプリケーションのサイトが見つからないか、ワークスペースがアーカイブされています。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } + } + }, + "/apps/annotations": { + "post": { + "summary": "アノテーションを作成", + "description": "新しいアノテーションを作成します。アノテーションは、アプリがレスポンスを生成する代わりに直接マッチして返すことができる、事前定義された質問と回答のペアを提供します。", + "operationId": "createChatflowAnnotationJa", + "tags": [ + "アノテーション管理" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAnnotationRequest" + }, + "examples": { + "createAnnotation": { + "summary": "リクエスト例", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "アノテーションが正常に作成されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "createdAnnotation": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 0, + "created_at": 1705407629 + } + } + } + } + } + } + } + }, + "get": { + "summary": "アノテーションリストを取得", + "description": "アプリケーションのアノテーションをページネーションリストで取得します。キーワード検索によるフィルタリングをサポートしています。", + "operationId": "listChatflowAnnotationsJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1 ページあたりの件数です。", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "keyword", + "in": "query", + "description": "質問または回答の内容でアノテーションをフィルタリングするためのキーワードです。", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "アノテーションリストの取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationListResponse" + }, + "examples": { + "annotationList": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 5, + "created_at": 1705407629 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + } + } + } + }, + "/apps/annotations/{annotation_id}": { + "put": { + "summary": "アノテーションを更新", + "description": "既存のアノテーションの質問と回答を更新します。", + "operationId": "updateChatflowAnnotationJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "更新するアノテーションの一意の識別子です。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateAnnotationRequest" + }, + "examples": { + "updateAnnotation": { + "summary": "リクエスト例", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "アノテーションが正常に更新されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "updatedAnnotation": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", + "hit_count": 5, + "created_at": 1705407629 + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : アノテーションを編集する権限がありません。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : アノテーションが存在しません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } + } + }, + "delete": { + "summary": "アノテーションを削除", + "description": "アノテーションとその関連するヒット履歴を削除します。", + "operationId": "deleteChatflowAnnotationJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "削除するアノテーションの一意の識別子です。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "アノテーションが正常に削除されました。" + }, + "403": { + "description": "`forbidden` : アノテーションを編集する権限がありません。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : アノテーションが存在しません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } + } + } + }, + "/apps/annotation-reply/{action}": { + "post": { + "summary": "アノテーション返信を設定", + "description": "アノテーション返信機能を有効または無効にします。有効にする場合は埋め込みモデルの設定が必要です。非同期で実行されます——[アノテーション返信の初期設定タスクステータスを取得](/api-reference/アノテーション管理/アノテーション返信の初期設定タスクステータスを取得) で進捗を追跡します。", + "operationId": "setChatflowAnnotationReplyJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "実行するアクションです。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" + }, + "examples": { + "enableAnnotationReply": { + "summary": "リクエスト例", + "value": { + "score_threshold": 0.9, + "embedding_provider_name": "openai", + "embedding_model_name": "text-embedding-3-small" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "アノテーション返信設定タスクが開始されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" + }, + "examples": { + "annotationReplyResponse": { + "summary": "レスポンス例", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "waiting" + } + } + } + } + } + } + } + } + }, + "/apps/annotation-reply/{action}/status/{job_id}": { + "get": { + "summary": "アノテーション返信の初期設定タスクステータスを取得", + "description": "[アノテーション返信を設定](/api-reference/アノテーション管理/アノテーション返信を設定) で開始された非同期アノテーション返信設定ジョブのステータスを取得します。", + "operationId": "getChatflowAnnotationReplyStatusJa", + "tags": [ + "アノテーション管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "アクションタイプです。[アノテーション返信を設定](/api-reference/アノテーション管理/アノテーション返信を設定) の呼び出しと一致する必要があります。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "[アノテーション返信を設定](/api-reference/アノテーション管理/アノテーション返信を設定) から返されたジョブ ID です。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "タスクステータスの取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "レスポンス例", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 指定されたジョブが存在しません。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "The job does not exist." + } + } + } + } + } + } + } + } + }, + "/workflows/run/{workflow_run_id}": { + "get": { + "summary": "ワークフロー実行詳細を取得", + "description": "ワークフロー実行 ID に基づいて、ワークフロータスクの現在の実行結果を取得します。", + "operationId": "getChatflowWorkflowRunDetailJa", + "tags": [ + "ワークフロー実行" + ], + "parameters": [ + { + "name": "workflow_run_id", + "in": "path", + "required": true, + "description": "ワークフロー実行 ID です。ストリーミングイベントまたはメッセージメタデータから取得できます。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ワークフロー実行の詳細の取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "レスポンス例", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } + } + } + }, + "400": { + "description": "`not_workflow_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ワークフロー実行記録が見つかりません。", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } + } + } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "ワークフローログ一覧を取得", + "description": "フィルタリングオプション付きでワークフロー実行ログをページネーションで取得します。", + "operationId": "listChatflowWorkflowLogsJa", + "tags": [ + "ワークフロー実行" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "ログ内を検索するキーワードです。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "実行ステータスでフィルタリングします。", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "1 ページあたりの件数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "この ISO 8601 タイムスタンプ以前に作成されたログをフィルタリングします。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "この ISO 8601 タイムスタンプ以降に作成されたログをフィルタリングします。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "エンドユーザーセッション ID でフィルタリングします。", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "アカウント ID でフィルタリングします。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ワークフローログの取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "レスポンス例", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0 + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_chatflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } + } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "APIキー認証。すべてのAPIリクエストには、Authorization HTTPヘッダーにAPIキーを `Bearer {API_KEY}` の形式で含めてください。APIキーはサーバー側に保存し、クライアント側で共有または保存しないことを強くお勧めします。" } - }, - "parameters": { - "PageQueryParamJp": { "name": "page", "in": "query", "description": "（任意）ページ番号。デフォルト値：1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamJp": { "name": "limit", "in": "query", "description": "（任意）1ページあたりの件数。デフォルト値：20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Jp": { "name": "limit", "in": "query", "description": "1回のリクエストで返す記録の数、デフォルトは20です。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100Jp": { "name": "limit", "in": "query", "description": "1回のリクエストで返す記録の数、デフォルトは最新の20件です。最大100、最小1。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParamJp": { "name": "user", "in": "query", "required": true, "description": "ユーザー識別子。アプリケーション内で開発者によって一意に定義されるべきです。**重要な注意事項**: Service API は WebApp で作成された対話を共有しません。API を通じて作成された対話は、WebApp インターフェースで作成されたものとは分離されています。", "schema": { "type": "string" } }, - "ConversationIdQueryParamJp": { "name": "conversation_id", "in": "query", "required": true, "description": "会話ID。", "schema": { "type": "string", "format": "uuid" } }, - "LastIdQueryParamJp": { "name": "last_id", "in": "query", "description": "(Optional)現在のページの最後の記録のID、デフォルトはnullです。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, - "SortByQueryParamJp": { "name": "sort_by", "in": "query", "description": "(Optional)ソートフィールド、デフォルト：-updated_at（更新時間で降順にソート）。利用可能な値：created_at, -created_at, updated_at, -updated_at。'-'は逆順を表します。", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParamJp": { "name": "conversation_id", "in": "path", "required": true, "description": "会話ID。", "schema": { "type": "string", "format": "uuid" } } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 認証です。すべての API リクエストにおいて、`Authorization` HTTP ヘッダーに `Bearer ` プレフィックスを付けた API Key を含めてください。例：`Authorization: Bearer {API_KEY}`。**API Key はサーバーサイドに保存し、クライアントサイドで共有・保存しないことを強く推奨します。API Key の漏洩は深刻な結果につながる可能性があります。**" + } }, "responses": { - "BadRequestGenericJp": { "description": "リクエストパラメータエラー。考えられる原因：invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "BadRequestFileJp": { "description": "ファイル操作リクエストエラー。考えられる原因：no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "FileTooLargeJp": { "description": "ファイルが大きすぎます (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "UnsupportedFileTypeFileJp": { "description": "サポートされていないファイルタイプ (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "S3ErrorFileJp": { "description": "S3ストレージサービスエラー。考えられる原因：s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "InternalServerErrorJp": { "description": "内部サーバーエラー。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "SuccessResultJp": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFoundJp": { "description": "会話が存在しません。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "EndUserNotFoundJp": { "description": "エンドユーザーが見つかりません。エラーコード：`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } } + "SuccessResult": { + "description": "操作が成功しました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "結果ステータス。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "ChatflowRequestJp": { + "ChatRequest": { "type": "object", - "required": ["query", "user"], + "required": [ + "inputs", + "query", + "user" + ], "properties": { - "query": { "type": "string", "description": "ユーザー入力/質問内容。" }, + "query": { + "type": "string", + "description": "ユーザーの入力/質問内容です。" + }, "inputs": { "type": "object", - "description": "アプリによって定義されたさまざまな変数値の入力を許可します。変数がファイルタイプの場合、InputFileObjectJp オブジェクトを指定します。", - "additionalProperties": { - "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "$ref": "#/components/schemas/InputFileObjectJp" } ] - }, - "default": {} + "description": "アプリで定義されたさまざまな変数の値を入力できます。キーと値のペアを含みます。アプリが期待する変数名と型については、[アプリケーションのパラメータ情報を取得](/api-reference/アプリケーション設定/アプリケーションのパラメータ情報を取得) レスポンスの `user_input_form` フィールドを参照してください。", + "additionalProperties": true }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "応答の返却モード。streaming (推奨) はSSEを使用。blocking は実行完了後に結果を返します (Cloudflareの100秒タイムアウト制限あり)。" }, - "user": { "type": "string", "description": "ユーザー識別子。アプリケーション内で一意であるべきです。**重要な注意事項**: Service API は WebApp で作成された対話を共有しません。API を通じて作成された対話は、WebApp インターフェースで作成されたものとは分離されています。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。以前のチャット記録に基づいて会話を続ける場合に必要です。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectJp" }, "description": "ファイルリスト。モデルがビジョン機能をサポートしている場合に利用可能です。" }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "タイトルを自動生成。デフォルトはtrue。" } + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "レスポンスの返却モード。`streaming`（推奨）は SSE を使用します。`blocking` は完了後に返却します（長時間の処理では中断される場合があります）。Cloudflare のタイムアウトは `100 s` です。省略した場合、デフォルトでブロッキングモードになります。" + }, + "user": { + "type": "string", + "description": "アプリケーション内で一意のユーザー識別子です。この識別子はデータアクセスの範囲を限定します——会話、メッセージ、ファイルは同じ `user` 値でクエリした場合にのみ表示されます。" + }, + "conversation_id": { + "type": "string", + "description": "会話を継続するための会話 ID です。前のメッセージの `conversation_id` を渡します。新しい会話を開始するには、このフィールドを省略するか空文字列を渡します。レスポンスで `conversation_id` が返されます——以降のメッセージでこの値を渡すとその会話を継続できます。" + }, + "files": { + "type": "array", + "description": "マルチモーダル理解用のファイルリストです。画像、ドキュメント、音声、動画を含みます。ローカルファイルを添付するには、まず [ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) でアップロードし、返された `id` を `upload_file_id` として `transfer_method: local_file` で使用します。", + "items": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "ファイルタイプ。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "転送方法です。ファイル URL の場合は `remote_url`、アップロードファイルの場合は `local_file` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファイル URL（`transfer_method` が `remote_url` の場合は必須）です。" + }, + "upload_file_id": { + "type": "string", + "description": "[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API から取得したアップロード済みファイル ID です（`transfer_method` が `local_file` の場合は必須）。" + } + } + } + }, + "auto_generate_name": { + "type": "boolean", + "description": "会話タイトルを自動生成します。`false` の場合、[会話の名前を変更](/api-reference/会話管理/会話の名前を変更) API で `auto_generate: true` を設定して非同期でタイトルを生成します。", + "default": true + }, + "workflow_id": { + "type": "string", + "description": "実行する公開済みワークフローバージョンの ID を指定します。指定しない場合、最新の公開バージョンが使用されます。" + } } }, - "InputFileObjectJp": { + "ChatCompletionResponse": { "type": "object", - "required": ["type", "transfer_method"], "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "ファイルタイプ。document: TXT,MD,PDF等; image: JPG,PNG等; audio: MP3,WAV等; video: MP4,MOV等; custom: その他。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "転送方法。remote_url は画像URL / local_file はファイルアップロード用" }, - "url": { "type": "string", "format": "url", "description": "画像URL（転送方法が remote_url の場合）" }, - "upload_file_id": { "type": "string", "format":"uuid", "description": "アップロードされたファイルID、事前にファイルアップロードAPIで取得する必要があります（転送方法が local_file の場合）" } + "event": { + "type": "string", + "description": "イベントタイプ。`message` に固定されています。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "リクエスト追跡およびレスポンス停止 API 用のタスク ID です。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "このレスポンスイベントの一意 ID です。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "一意のメッセージ ID です。フィードバックや推奨質問のエンドポイントを呼び出す際に `message_id` パラメータとして使用します。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "mode": { + "type": "string", + "description": "アプリモード、`advanced-chat` 固定です。" + }, + "answer": { + "type": "string", + "description": "完全なレスポンスコンテンツ。" + }, + "metadata": { + "type": "object", + "description": "使用量と検索リソースを含むメタデータ。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用された検索リソースのリスト。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "メッセージ作成タイムスタンプ（Unix エポック秒）。" + } + } + }, + "ChunkChatEvent": { + "type": "object", + "description": "ストリーミングモードにおける Server-Sent Event チャンクのベーススキーマです。", + "properties": { + "event": { + "type": "string", + "description": "イベントの種類です。", + "enum": [ + "message", + "tts_message", + "tts_message_end", + "message_file", + "message_end", + "message_replace", + "workflow_started", + "workflow_finished", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "workflow_paused", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "agent_log", + "text_chunk", + "text_replace", + "error", + "ping" + ] + } }, - "anyOf": [ + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventChatMessage", + "tts_message": "#/components/schemas/StreamEventChatTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", + "message_file": "#/components/schemas/StreamEventChatMessageFile", + "message_end": "#/components/schemas/StreamEventChatMessageEnd", + "message_replace": "#/components/schemas/StreamEventChatMessageReplace", + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "text_chunk": "#/components/schemas/StreamEventChatTextChunk", + "text_replace": "#/components/schemas/StreamEventChatTextReplace", + "error": "#/components/schemas/StreamEventChatError", + "ping": "#/components/schemas/StreamEventChatPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "description": "ストリームイベントの基本プロパティです。", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "タスク ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "一意のメッセージ ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + } + } + }, + "StreamEventChatMessage": { + "allOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "$ref": "#/components/schemas/ChunkChatEvent" }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format":"uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "answer": { + "type": "string", + "description": "LLM が返したテキストチャンクです。" + } + } } ] }, - "ChatCompletionResponseJp": { - "type": "object", "description": "ブロッキングモードでの完全なアプリ結果。", + "StreamEventChatTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリームイベント（base64 エンコードの Mp3）です。自動再生が有効な場合に利用できます。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 エンコードされた MP3 音声チャンク。すべてのチャンクを順番にデコードして連結すると、完全な音声ファイルが生成されます。" + } + } + } + ] + }, + "StreamEventChatTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリーム終了イベント。", + "properties": { + "audio": { + "type": "string", + "description": "空の文字列。音声ストリームの終了を示します。" + } + } + } + ] + }, + "StreamEventChatMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "メッセージファイルイベント。ツールによって作成された新しいファイルです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ファイルの一意の ID。" + }, + "type": { + "type": "string", + "description": "ファイルタイプ（例：`image`）。" + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "このファイルの所有者。ここでは常に `assistant` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファイルのリモート URL。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + } + } + } + ] + }, + "StreamEventChatMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "メッセージ終了イベント、ストリーミングが終了しました。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "メッセージの一意な ID。" + }, + "metadata": { + "type": "object", + "description": "使用量と検索リソースを含むメタデータ。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用された検索リソースのリスト。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } + ] + }, + "StreamEventChatMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "メッセージコンテンツ置換イベント（例：コンテンツモデレーションによるもの）。", + "properties": { + "answer": { + "type": "string", + "description": "置換コンテンツ。" + }, + "reason": { + "type": "string", + "description": "コンテンツ置換の理由。" + } + } + } + ] + }, + "StreamEventChatError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ストリーミング中のエラーイベント。", + "properties": { + "status": { + "type": "integer", + "description": "HTTP ステータスコード。" + }, + "code": { + "type": "string", + "description": "エラーコード。" + }, + "message": { + "type": "string", + "description": "エラーメッセージ。" + } + } + } + ] + }, + "StreamEventChatPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "接続を維持するための Ping イベント。" + } + ] + }, + "Usage": { + "type": "object", + "description": "モデルの使用情報です。", "properties": { - "event": { "type": "string", "example": "message", "description": "イベントタイプ、固定で `message`。" }, - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "id": { "type": "string", "format": "uuid", "description": "ユニークID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。" }, - "mode": { "type": "string", "example": "chat", "description": "アプリモード、`chat`として固定。" }, - "answer": { "type": "string", "description": "完全な応答内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataJp" }, - "created_at": { "type": "integer", "format": "int64", "description": "メッセージ作成タイムスタンプ。" } + "prompt_tokens": { + "type": "integer", + "description": "プロンプト内のトークン数。" + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "プロンプトトークンあたりの単価。" + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "プロンプトトークンの価格単位。" + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "プロンプトトークンの合計価格。" + }, + "completion_tokens": { + "type": "integer", + "description": "補完のトークン数。" + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "補完トークンあたりの単価。" + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "補完トークンの価格単位。" + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "補完トークンの合計価格。" + }, + "total_tokens": { + "type": "integer", + "description": "使用されたトークンの合計数。" + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "すべてのトークンの合計価格。" + }, + "currency": { + "type": "string", + "description": "課金通貨。" + }, + "latency": { + "type": "number", + "format": "double", + "description": "レイテンシ（秒）。" + } } }, - "ResponseMetadataJp": { - "type": "object", "description": "メタデータ。", - "properties": { "usage": { "$ref": "#/components/schemas/UsageJp" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJp" }, "description": "引用と帰属リスト。" } } - }, - "ChunkChatflowEventJp": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "workflow_started", "node_started", "node_finished", "workflow_finished", "error", "ping"], "description": "イベントタイプ。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "message": "#/components/schemas/StreamEventChatMessageJp", "message_file": "#/components/schemas/StreamEventMessageFileJp", - "message_end": "#/components/schemas/StreamEventMessageEndJp", "tts_message": "#/components/schemas/StreamEventTtsMessageJp", - "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndJp", "message_replace": "#/components/schemas/StreamEventMessageReplaceJp", - "workflow_started": "#/components/schemas/StreamEventWorkflowStartedJp", "node_started": "#/components/schemas/StreamEventNodeStartedJp", - "node_finished": "#/components/schemas/StreamEventNodeFinishedJp", "workflow_finished": "#/components/schemas/StreamEventWorkflowFinishedJp", - "error": "#/components/schemas/StreamEventErrorJp", "ping": "#/components/schemas/StreamEventPingJp" - }} - }, - "StreamEventBaseChatJp": { - "type": "object", "properties": { - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。" }, - "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } + "RetrieverResource": { + "type": "object", + "description": "検索リソースの引用および帰属情報です。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "検索リソースの一意の ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "このリソースが属するメッセージの ID。" + }, + "position": { + "type": "integer", + "description": "リスト内のリソースの位置。" + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "ナレッジベース ID。" + }, + "dataset_name": { + "type": "string", + "description": "ナレッジベース名。" + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "ドキュメント ID。" + }, + "document_name": { + "type": "string", + "description": "ドキュメント名。" + }, + "data_source_type": { + "type": "string", + "description": "データソースのタイプ。" + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "ドキュメント内の特定のチャンクの ID。" + }, + "score": { + "type": "number", + "format": "float", + "description": "リソースの関連性スコア。" + }, + "hit_count": { + "type": "integer", + "description": "このチャンクがヒットした回数。" + }, + "word_count": { + "type": "integer", + "description": "チャンクの単語数。" + }, + "segment_position": { + "type": "integer", + "description": "ドキュメント内のチャンクの位置。" + }, + "index_node_hash": { + "type": "string", + "description": "インデックスノードのハッシュ。" + }, + "content": { + "type": "string", + "description": "リソースからのコンテンツスニペット。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "チャンクコンテンツの要約。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ（Unix エポック秒）。" + } } }, - "StreamEventChatMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLMが返したテキストチャンク内容。" } } } ] }, - "StreamEventMessageFileJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ファイル一意ID。" }, "type": { "type": "string", "enum": ["image"], "description": "ファイルタイプ、現在はimageのみ。" }, "belongs_to": { "type": "string", "enum": ["assistant"], "description": "所属、ここではassistantのみ。" }, "url": { "type": "string", "format": "url", "description": "ファイルのリモートURL。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。" } } } ] }, - "StreamEventMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataJp" } } } ] }, - "StreamEventTtsMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64エンコードされたオーディオブロック。" } } } ] }, - "StreamEventTtsMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空の文字列。" } } } ] }, - "StreamEventMessageReplaceJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "置換内容（すべてのLLM返信テキストを直接置き換えます）。" } } } ] }, - "StreamEventWorkflowStartedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/WorkflowStartedDataJp" } } } ] }, - "WorkflowStartedDataJp": { "type": "object", "required": ["id", "workflow_id", "sequence_number", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワークフロー実行の一意ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "関連ワークフローのID。" }, "sequence_number": { "type": "integer", "description": "自己増加シリアル番号、アプリ内で自己増加し、1から始まります。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } }, - "StreamEventNodeStartedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/NodeStartedDataJp" } } } ] }, - "NodeStartedDataJp": { "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワークフロー実行の一意ID (文脈からノード実行IDであるべき)。" }, "node_id": { "type": "string", "format": "uuid", "description": "ノードのID。" }, "node_type": { "type": "string", "description": "ノードのタイプ。" }, "title": { "type": "string", "description": "ノードの名前。" }, "index": { "type": "integer", "description": "実行シーケンス番号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "オプションのプレフィックスノードID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ノードで使用されるすべての前のノード変数の内容。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始のタイムスタンプ。" } } }, - "StreamEventNodeFinishedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/NodeFinishedDataJp" } } } ] }, - "NodeFinishedDataJp": { "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "status", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ノード実行の一意ID。" }, "node_id": { "type": "string", "format": "uuid", "description": "ノードのID。" }, "node_type": { "type": "string", "description": "ノードのタイプ。" }, "title": { "type": "string", "description": "ノードの名前。" }, "index": { "type": "integer", "description": "実行シーケンス番号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "オプションのプレフィックスノードID。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "ノードで使用されるすべての前のノード変数の内容。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "オプションのノードプロセスデータ (JSON)。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "オプションの出力内容 (JSON)。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行の状態。" }, "error": { "type": "string", "nullable": true, "description": "オプションのエラー理由。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "オプションの使用される合計秒数。" }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadataJp" , "nullable": true, "description": "メタデータ"}, "created_at": { "type": "integer", "format": "int64", "description": "開始のタイムスタンプ。" } } }, - "NodeExecutionMetadataJp": { "type": "object", "description": "ノード実行メタデータ。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "オプションの使用されるトークン数。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "オプションの合計コスト (floatでdecimalを代用)。" }, "currency": { "type": "string", "nullable": true, "example": "USD", "description": "オプションの通貨。" } } }, - "StreamEventWorkflowFinishedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/WorkflowFinishedDataJp" } } } ] }, - "WorkflowFinishedDataJp": { "type": "object", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワークフロー実行のID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "関連ワークフローのID。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行の状態。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "オプションの出力内容 (JSON)。" }, "error": { "type": "string", "nullable": true, "description": "オプションのエラー理由。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "オプションの使用される合計秒数。" }, "total_tokens": { "type": "integer", "nullable": true, "description": "オプションの使用されるトークン数。" }, "total_steps": { "type": "integer", "default": 0, "description": "合計ステップ数、デフォルト0。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始時間。" }, "finished_at": { "type": "integer", "format": "int64", "description": "終了時間。" } } }, - "StreamEventErrorJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "status", "code", "message"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "一意のメッセージID（エラーイベントでは存在しない場合がある）。" }, "status": { "type": "integer", "description": "HTTPステータスコード。" }, "code": { "type": "string", "description": "エラーコード。" }, "message": { "type": "string", "description": "エラーメッセージ。" } } } ] }, - "StreamEventPingJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "description": "接続を維持するために10秒ごとにpingイベントが発生します。" } ] }, - "UsageJp": { "type": "object", "description": "モデル使用情報。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceJp": { "type": "object", "description": "引用と帰属リスト。", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } }, - "FileUploadResponseJp": { "type": "object", "description": "ファイルアップロード成功時の応答。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "ファイル名。" }, "size": { "type": "integer", "description": "ファイルサイズ（バイト）。" }, "extension": { "type": "string", "description": "ファイル拡張子。" }, "mime_type": { "type": "string", "description": "ファイルのMIMEタイプ。" }, "created_by": { "type": "string", "format": "uuid", "description": "エンドユーザーID。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } }, - "EndUserDetailJp": { + "FileUploadResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "一意のファイル ID。" + }, + "name": { + "type": "string", + "description": "ファイル名。" + }, + "size": { + "type": "integer", + "description": "ファイルサイズ（バイト）。" + }, + "extension": { + "type": "string", + "nullable": true, + "description": "ファイル拡張子。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "ファイルの MIME タイプ。" + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ファイルをアップロードしたユーザーの ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "アップロードタイムスタンプ（Unix エポック秒）。" + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "ファイルのプレビュー URL。" + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "ファイルのソース URL。" + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "ファイルの元の URL。" + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられたユーザーの ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられたテナントの ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられた会話の ID。" + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "ファイルのストレージキー。" + } } }, - "MessageFeedbackRequestJp": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "アップボートは`like`、ダウンボートは`dislike`、取り消しは`null`。" }, "user": { "type": "string", "description": "ユーザー識別子。" }, "content": { "type": "string", "nullable": true, "description": "メッセージフィードバックの具体的な内容。" } } }, - "AppFeedbacksResponseJp": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemJp" }, "description": "このアプリの「いいね」とフィードバックの一覧。" } } }, - "FeedbackItemJp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "SuggestedQuestionsResponseJp": { "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "description": "推奨質問のリスト。" } } }, - "ConversationHistoryResponseJp": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返された項目数。" }, "has_more": { "type": "boolean", "description": "次のページがあるかどうか。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessageItemJp" }, "description": "メッセージリスト。" } } }, - "ConversationMessageItemJp": { "type": "object", "description": "会話内の単一メッセージ。", "properties": { "id": { "type": "string", "format": "uuid", "description": "メッセージID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会話ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ユーザー入力パラメータ。" }, "query": { "type": "string", "description": "ユーザー入力/質問内容。" }, "answer": { "type": "string", "description": "応答メッセージ内容。" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItemJp" }, "description": "メッセージファイルリスト。" }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"], "description": "アップボートは`like` / ダウンボートは`dislike`。" } }, "description": "フィードバック情報。" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJp" }, "description": "引用と帰属リスト。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } }, - "MessageFileItemJp": { "type": "object", "description": "メッセージ内のファイル項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "ファイルタイプ、例：'image'。" }, "url": { "type": "string", "format": "url", "description": "プレビュー画像URL。" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "所属。" } } }, - "ConversationsListResponseJp": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返されたエントリ数。" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItemJp" }, "description": "会話のリスト。" } } }, - "ConversationListItemJp": { "type": "object", "description": "会話リスト内の単一項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "会話ID。" }, "name": { "type": "string", "description": "会話名。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ユーザー入力パラメータ。" }, "status": { "type": "string", "description": "会話状態。" }, "introduction": { "type": "string", "nullable": true, "description": "紹介。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" }, "updated_at": { "type": "integer", "format": "int64", "description": "更新タイムスタンプ。" } } }, - "ConversationRenameRequestJp": { "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true, "description": "(Optional)会話の名前。`auto_generate`が`true`の場合省略可。" }, "auto_generate": { "type": "boolean", "default": false, "description": "(Optional)タイトルを自動生成、デフォルトは`false`。" }, "user": { "type": "string", "description": "ユーザー識別子。" } } }, - "ConversationRenameResponseJp": { "$ref": "#/components/schemas/ConversationListItemJp" }, - "ConversationVariablesResponseJp": { "type": "object", "properties": { "limit": { "type": "integer", "description": "ページごとのアイテム数。" }, "has_more": { "type": "boolean", "description": "さらにアイテムがあるかどうか。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItemJp" }, "description": "変数のリスト。" } } }, - "ConversationVariableItemJp": { "type": "object", "description": "会話内の変数項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "変数ID。" }, "name": { "type": "string", "description": "変数名。" }, "value_type": { "type": "string", "description": "変数タイプ（文字列、数値、真偽値など）。" }, "value": { "type": "string", "description": "変数値。" }, "description": { "type": "string", "nullable": true, "description": "変数の説明。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最終更新タイムスタンプ。" } } }, - "AudioToTextRequestJp": { "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "オーディオファイル。サポート形式：`['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']`。サイズ制限：15MB。" }, "user": { "type": "string", "description": "ユーザー識別子。" } } }, - "AudioToTextResponseJp": { "type": "object", "properties": { "text": { "type": "string", "description": "出力テキスト。" } } }, - "TextToAudioJsonRequestJp": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "メッセージID（優先）。" }, "text": { "type": "string", "description": "音声生成コンテンツ。" }, "user": { "type": "string", "description": "ユーザー識別子。" }, "streaming": {"type": "boolean", "default": false, "description": "trueの場合、応答はオーディオチャンクのストリームになります。"} }, "description": "`user` が必要です。`message_id` または `text` を提供してください。" }, - "AppInfoResponseJp": { "type": "object", "description": "アプリケーションの基本情報。", "properties": { "name": { "type": "string", "description": "アプリケーションの名前。" }, "description": { "type": "string", "description": "アプリケーションの説明。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "アプリケーションのタグ。" } } }, - "ChatAppParametersResponseJp": { "type": "object", "description": "アプリケーションのパラメータ情報。", "properties": { "opening_statement": { "type": "string", "description": "開始の挨拶。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "開始時の推奨質問のリスト。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "答えを有効にした後の質問を提案します。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "音声からテキストへ。" }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" }, "voice": { "type": "string", "description": "音声タイプ。" }, "language": { "type": "string", "description": "言語。" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"], "description": "自動再生：enabled 有効, disabled 無効。" } }, "description": "テキストから音声へ。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "引用と帰属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "注釈返信。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemJp" }, "description": "ユーザー入力フォームの設定。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "画像設定。サポートされている画像タイプ：png, jpg, jpeg, webp, gif。" } }, "description": "ファイルアップロード設定。" }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer", "description": "ドキュメントアップロードサイズ制限（MB）。" }, "image_file_size_limit": { "type": "integer", "description": "画像ファイルアップロードサイズ制限（MB）。" }, "audio_file_size_limit": { "type": "integer", "description": "オーディオファイルアップロードサイズ制限（MB）。" }, "video_file_size_limit": { "type": "integer", "description": "ビデオファイルアップロードサイズ制限（MB）。" } }, "description": "システムパラメータ。" } } }, - "UserInputFormItemJp": { "type": "object", "description": "ユーザー入力フォームのコントロール項目。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperJp" }, { "$ref": "#/components/schemas/ParagraphControlWrapperJp" }, { "$ref": "#/components/schemas/SelectControlWrapperJp" } ] }, - "TextInputControlWrapperJp": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlJp" } }, "required":["text-input"] }, - "ParagraphControlWrapperJp": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlJp" } }, "required":["paragraph"] }, - "SelectControlWrapperJp": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlJp" } }, "required":["select"] }, - "TextInputControlJp": { "type": "object", "description": "テキスト入力コントロール。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" } } }, - "ParagraphControlJp": { "type": "object", "description": "段落テキスト入力コントロール。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" } } }, - "SelectControlJp": { "type": "object", "description": "ドロップダウンコントロール。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "オプション値。" } } }, - "AppMetaResponseJp": { "type": "object", "description": "アプリケーションのメタ情報。", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url", "description": "アイコンのURL。" }, { "$ref": "#/components/schemas/ToolIconDetailJp" } ] }, "description": "ツールアイコン。キーはツール名です。" } } }, - "ToolIconDetailJp": { "type": "object", "description": "ツールアイコン詳細。", "properties": { "background": { "type": "string", "description": "背景色（16進数形式）。" }, "content": { "type": "string", "description": "絵文字。" } } }, - "WebAppSettingsResponseJp": { "type": "object", "description": "アプリのWebApp設定。", "properties": { "title": { "type": "string", "description": "WebApp名。" }, "chat_color_theme": { "type": "string", "description": "チャットの色テーマ、16進数形式。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "チャットの色テーマを反転するかどうか。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "アイコンタイプ。" }, "icon": { "type": "string", "description": "アイコン。`emoji`タイプの場合は絵文字、`image`タイプの場合は画像URL。" }, "icon_background": { "type": "string", "description": "16進数形式の背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "アイコンのURL。" }, "description": { "type": "string", "description": "説明。" }, "copyright": { "type": "string", "description": "著作権情報。" }, "privacy_policy": { "type": "string", "description": "プライバシーポリシーのリンク。" }, "custom_disclaimer": { "type": "string", "description": "カスタム免責事項。" }, "default_language": { "type": "string", "description": "デフォルト言語。" }, "show_workflow_steps": { "type": "boolean", "description": "ワークフローの詳細を表示するかどうか。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "WebAppのアイコンをチャット内のロボットアイコンに置き換えるかどうか。" } } }, - "ErrorResponseJp": { "type": "object", "description": "エラー応答。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTPステータスコード。" }, "code": { "type": "string", "nullable": true, "description": "エラーコード。" }, "message": { "type": "string", "description": "エラーメッセージ。" } } } + "EndUserDetail": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "エンドユーザー ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "テナント ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "アプリケーション ID。" + }, + "type": { + "type": "string", + "description": "エンドユーザーのタイプ。Service API ユーザーの場合は常に `service_api` です。" + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "API リクエストで提供された `user` 識別子です（例：[チャットメッセージを送信](/api-reference/チャットメッセージ/チャットメッセージを送信) の `user` フィールド）。" + }, + "name": { + "type": "string", + "nullable": true, + "description": "エンドユーザー名。" + }, + "is_anonymous": { + "type": "boolean", + "description": "ユーザーが匿名かどうかを示します。元の API リクエストで `user` 識別子が提供されなかった場合、`true` になります。" + }, + "session_id": { + "type": "string", + "description": "セッション識別子。デフォルトは `external_user_id` の値です。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最終更新タイムスタンプ。" + } + } + }, + "MessageFeedbackRequest": { + "type": "object", + "description": "メッセージフィードバックを送信するためのリクエストボディ。", + "required": [ + "user" + ], + "properties": { + "rating": { + "type": "string", + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "フィードバック評価。以前送信したフィードバックを取り消すには `null` に設定します。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。開発者が定義し、アプリケーション内での一意性を確保する必要があります。" + }, + "content": { + "type": "string", + "description": "追加の詳細を提供する任意のテキストフィードバック。" + } + } + }, + "AppFeedbacksResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "フィードバック項目のリスト。", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } + } + } + }, + "FeedbackItem": { + "type": "object", + "description": "単一のフィードバック項目。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "フィードバック ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "アプリケーション ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "メッセージ ID。" + }, + "rating": { + "type": "string", + "description": "フィードバック評価。肯定的な場合は `like`、否定的な場合は `dislike`。" + }, + "content": { + "type": "string", + "nullable": true, + "description": "任意のテキストフィードバック。" + }, + "from_source": { + "type": "string", + "description": "フィードバックのソース。API 経由でエンドユーザーが送信したフィードバックの場合は `user`、コンソールから送信されたフィードバックの場合は `admin`。" + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "フィードバックを送信したエンドユーザー ID。`from_source` が `user` の場合に存在します。" + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "フィードバックを送信したアカウント ID。`from_source` が `admin` の場合に存在します。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最終更新タイムスタンプ。" + } + } + }, + "SuggestedQuestionsResponse": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "結果ステータス。" + }, + "data": { + "type": "array", + "items": { + "type": "string" + }, + "description": "提案された質問のリストです。" + } + } + }, + "ConversationHistoryResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "has_more": { + "type": "boolean", + "description": "さらにメッセージがあるかどうかです。" + }, + "data": { + "type": "array", + "description": "メッセージのリストです。", + "items": { + "$ref": "#/components/schemas/ConversationMessageItem" + } + } + } + }, + "ConversationMessageItem": { + "type": "object", + "description": "会話内の単一メッセージです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "メッセージ ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "parent_message_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "スレッド会話の親メッセージ ID です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "このメッセージの入力変数です。" + }, + "query": { + "type": "string", + "description": "ユーザークエリテキストです。" + }, + "answer": { + "type": "string", + "description": "アシスタントの回答テキストです。" + }, + "status": { + "type": "string", + "description": "メッセージステータスです。成功したメッセージの場合は `normal`、生成に失敗した場合は `error` です。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "`status` が `error` の場合のエラーメッセージです。" + }, + "message_files": { + "type": "array", + "description": "このメッセージに添付されたファイルです。", + "items": { + "$ref": "#/components/schemas/MessageFileItem" + } + }, + "feedback": { + "type": "object", + "nullable": true, + "description": "このメッセージのユーザーフィードバックです。", + "properties": { + "rating": { + "type": "string", + "description": "フィードバック評価。肯定的な場合は `like`、否定的な場合は `dislike`。" + } + } + }, + "retriever_resources": { + "type": "array", + "description": "このメッセージに使用された検索リソースです。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + }, + "agent_thoughts": { + "type": "array", + "description": "このメッセージのエージェント思考です。", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ（Unix エポック秒）。" + }, + "extra_contents": { + "type": "array", + "description": "このメッセージに関連する追加の実行コンテンツです。chatflow ワークフローの人的介入ノードからのフォームデータなどが含まれます。", + "items": { + "$ref": "#/components/schemas/HumanInputContent" + } + } + } + }, + "MessageFileItem": { + "type": "object", + "description": "メッセージに添付されたファイルです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "元のファイル名です。" + }, + "type": { + "type": "string", + "description": "ファイルの種類（例: `image`）です。" + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "ファイルのプレビュー URL。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "ファイルの MIME タイプ。" + }, + "size": { + "type": "integer", + "nullable": true, + "description": "ファイルサイズ（バイト）。" + }, + "transfer_method": { + "type": "string", + "description": "使用された転送方法です。`remote_url` は URL ベースのファイル、`local_file` はアップロード済みファイル、`tool_file` はツール生成ファイルを示します。" + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "このファイルの所有者です。ユーザーがアップロードしたファイルの場合は `user`、アシスタントが生成したファイルの場合は `assistant` です。" + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "`local_file` で転送された場合のアップロードファイル ID です。" + } + } + }, + "AgentThoughtItem": { + "type": "object", + "description": "メッセージ内のエージェント思考ステップです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "エージェント思考 ID です。" + }, + "chain_id": { + "type": "string", + "nullable": true, + "description": "この思考のチェーン ID です。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "この思考が属する一意のメッセージ ID です。" + }, + "position": { + "type": "integer", + "description": "この思考の位置です。" + }, + "thought": { + "type": "string", + "description": "LLM が思考している内容です。" + }, + "tool": { + "type": "string", + "description": "呼び出されたツール（`;` で区切り）です。" + }, + "tool_labels": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "使用されたツールのラベルです。" + }, + "tool_input": { + "type": "string", + "description": "ツールの入力（JSON 形式）です。" + }, + "observation": { + "type": "string", + "description": "ツール呼び出しからのレスポンスです。" + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "この思考に関連するファイル ID です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + } + } + }, + "ConversationsListResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "has_more": { + "type": "boolean", + "description": "さらに会話があるかどうかです。" + }, + "data": { + "type": "array", + "description": "会話のリストです。", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } + } + } + }, + "ConversationListItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "name": { + "type": "string", + "description": "会話名です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "会話の入力変数です。" + }, + "status": { + "type": "string", + "description": "会話ステータスです。アクティブな会話の場合は `normal` です。" + }, + "introduction": { + "type": "string", + "description": "会話の紹介文です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最終更新タイムスタンプ。" + } + } + }, + "ConversationRenameRequest": { + "type": "object", + "description": "会話の名前変更用リクエストボディです。", + "required": [ + "user" + ], + "properties": { + "name": { + "type": "string", + "description": "会話の名前です。`auto_generate` が `false` の場合は必須です。" + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "会話名を自動生成します。`true` の場合、`name` フィールドは無視されます。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子です。" + } + } + }, + "ConversationVariablesResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "has_more": { + "type": "boolean", + "description": "次のページがあるかどうかです。" + }, + "data": { + "type": "array", + "description": "会話変数のリストです。", + "items": { + "$ref": "#/components/schemas/ConversationVariableItem" + } + } + } + }, + "ConversationVariableItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Variable ID." + }, + "name": { + "type": "string", + "description": "変数名です。" + }, + "value_type": { + "type": "string", + "description": "変数の値の型です。指定可能な値：`string`、`number`、`object`、`secret`、`file`、`boolean`、`array[any]`、`array[string]`、`array[number]`、`array[object]`、`array[file]`、`array[boolean]`。" + }, + "value": { + "type": "string", + "description": "変数値（複雑な型の場合は JSON 文字列）。" + }, + "description": { + "type": "string", + "description": "変数の説明です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最終更新タイムスタンプ。" + } + } + }, + "ConversationVariableUpdateRequest": { + "type": "object", + "description": "会話変数を更新するためのリクエストボディです。", + "required": [ + "value" + ], + "properties": { + "value": { + "description": "変数の新しい値。変数の期待される型と一致する必要があります。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "音声からテキストへの変換のリクエストボディ。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音声ファイルです。対応形式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。上限：`30 MB`。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "音声認識からの出力テキスト。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "テキストから音声への変換のリクエストボディ。`message_id` または `text` のいずれかを指定してください。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "メッセージ ID です。両方が指定された場合、`text` よりも優先されます。" + }, + "text": { + "type": "string", + "description": "変換する音声コンテンツ。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + }, + "voice": { + "type": "string", + "description": "テキスト読み上げに使用する音声。利用可能な音声は、このアプリに設定された TTS プロバイダーによって異なります。デフォルトには[アプリケーションのパラメータ情報を取得](/api-reference/アプリケーション設定/アプリケーションのパラメータ情報を取得) → `text_to_speech.voice` の `voice` 値を使用してください。" + }, + "streaming": { + "type": "boolean", + "description": "ストリーミングレスポンスを有効にするかどうか。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "アプリケーション名。" + }, + "description": { + "type": "string", + "description": "アプリケーションの説明。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "アプリケーションタグ。" + }, + "mode": { + "type": "string", + "description": "アプリケーションモード。`completion` はテキスト生成アプリ、`chat` は基本チャットアプリ、`agent-chat` はエージェントベースのアプリ、`advanced-chat` は Chatflow アプリ、`workflow` はワークフローアプリです。" + }, + "author_name": { + "type": "string", + "description": "アプリケーション作成者の名前。" + } + } + }, + "ChatAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "会話開始時に表示されるオープニングメッセージです。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "推奨される初期質問のリスト。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答後の推奨質問の設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "音声からテキストへの変換設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "テキストから音声への変換設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + }, + "voice": { + "type": "string", + "description": "TTS の音声識別子。" + }, + "language": { + "type": "string", + "description": "TTS の言語。" + }, + "autoPlay": { + "type": "string", + "description": "自動再生設定です。音声を自動再生するには `enabled`、手動再生を要求するには `disabled` を指定します。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "検索リソースの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "アノテーション返信の設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "類似コンテンツの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "センシティブワードフィルタリングの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "user_input_form": { + "type": "array", + "description": "ユーザー入力フォーム要素のリスト。", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "ファイルアップロードの設定。", + "properties": { + "image": { + "type": "object", + "description": "画像アップロードの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "画像アップロードが有効かどうか。" + }, + "number_limits": { + "type": "integer", + "description": "最大画像数。" + }, + "detail": { + "type": "string", + "description": "画像の詳細レベル。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "許可された転送方法。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "システムレベルのパラメータと制限。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "最大ファイルサイズ（MB）。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最大画像ファイルサイズ（MB）。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最大音声ファイルサイズ（MB）。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最大動画ファイルサイズ（MB）。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "ワークフローファイルアップロードの最大ファイル数。" + } + } + } + } + }, + "UserInputFormItem": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } + ] + }, + "TextInputControlWrapper": { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } + }, + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } + }, + "SelectControlWrapper": { + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } + }, + "TextInputControl": { + "type": "object", + "description": "テキスト入力フォームコントロールです。", + "properties": { + "label": { + "type": "string", + "description": "表示ラベルです。" + }, + "variable": { + "type": "string", + "description": "変数名です。" + }, + "required": { + "type": "boolean", + "description": "入力が必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルト値です。" + } + } + }, + "ParagraphControl": { + "type": "object", + "description": "段落（複数行テキスト）フォームコントロールです。", + "properties": { + "label": { + "type": "string", + "description": "表示ラベルです。" + }, + "variable": { + "type": "string", + "description": "変数名です。" + }, + "required": { + "type": "boolean", + "description": "入力が必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルト値です。" + } + } + }, + "SelectControl": { + "type": "object", + "description": "セレクト（ドロップダウン）フォームコントロールです。", + "properties": { + "label": { + "type": "string", + "description": "表示ラベルです。" + }, + "variable": { + "type": "string", + "description": "変数名です。" + }, + "required": { + "type": "boolean", + "description": "選択が必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルトで選択される値。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "このフォームコントロールの選択可能な値のリスト。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "アイコンの URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "ツールアイコン。キーはツール名です。" + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "絵文字を使用したツールアイコンの詳細。", + "properties": { + "background": { + "type": "string", + "description": "16進数形式の背景色。" + }, + "content": { + "type": "string", + "description": "Emoji コンテンツ。" + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp タイトル。" + }, + "chat_color_theme": { + "type": "string", + "description": "チャットカラーテーマ。" + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "チャットカラーテーマが反転しているかどうか。" + }, + "icon_type": { + "type": "string", + "description": "使用されるアイコンのタイプ。`emoji` は絵文字アイコン、`image` はアップロードされた画像アイコンです。" + }, + "icon": { + "type": "string", + "description": "アイコンのコンテンツ（絵文字または画像 ID）。" + }, + "icon_background": { + "type": "string", + "description": "アイコンの背景色。" + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "アイコン画像の URL。" + }, + "description": { + "type": "string", + "description": "WebApp の説明。" + }, + "copyright": { + "type": "string", + "description": "著作権テキスト。" + }, + "privacy_policy": { + "type": "string", + "description": "プライバシーポリシー URL。" + }, + "custom_disclaimer": { + "type": "string", + "description": "カスタム免責事項テキスト。" + }, + "default_language": { + "type": "string", + "description": "デフォルト言語コード。" + }, + "show_workflow_steps": { + "type": "boolean", + "description": "ワークフローステップを表示するかどうか。" + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "アプリアイコンを回答アイコンとして使用するかどうか。" + } + } + }, + "AnnotationListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "description": "現在のページのアノテーション項目のリストです。" + }, + "has_more": { + "type": "boolean", + "description": "現在の結果セットの後にさらにページがある場合は `true` です。" + }, + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "クエリに一致するアノテーションの合計数です。" + }, + "page": { + "type": "integer", + "description": "現在のページ番号です。" + } + } + }, + "AnnotationItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "アノテーションの一意識別子です。" + }, + "question": { + "type": "string", + "nullable": true, + "description": "このアノテーションをトリガーする質問テキストです。" + }, + "answer": { + "type": "string", + "nullable": true, + "description": "アノテーションがマッチした際に返される定義済みの回答です。" + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "このアノテーションがマッチして返信として返された回数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "作成タイムスタンプ（Unix エポック秒）。" + } + } + }, + "CreateAnnotationRequest": { + "type": "object", + "description": "新しいアノテーションを作成するためのリクエストボディです。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "アノテーションの質問です。" + }, + "answer": { + "type": "string", + "description": "アノテーションの回答です。" + } + } + }, + "UpdateAnnotationRequest": { + "type": "object", + "description": "アノテーション更新のリクエストボディです。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "更新されたアノテーションの質問です。" + }, + "answer": { + "type": "string", + "description": "更新されたアノテーションの回答です。" + } + } + }, + "InitialAnnotationReplySettingsRequest": { + "type": "object", + "description": "アノテーション返信設定を構成するためのリクエストボディです。", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], + "properties": { + "embedding_provider_name": { + "type": "string", + "description": "埋め込みモデルプロバイダーの名前（例：`openai`、`cohere`）です。" + }, + "embedding_model_name": { + "type": "string", + "description": "アノテーションマッチングに使用する埋め込みモデルの名前です（例：`text-embedding-3-small`）。" + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "アノテーションがマッチとみなされるための最低類似度スコアです。値が高いほど、より正確なマッチが必要になります。", + "minimum": 0, + "maximum": 1 + } + } + }, + "InitialAnnotationReplySettingsResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "非同期ジョブ ID です。[アノテーション返信の初期設定タスクステータスを取得](/api-reference/アノテーション管理/アノテーション返信の初期設定タスクステータスを取得) と組み合わせて進捗を追跡します。" + }, + "job_status": { + "type": "string", + "description": "現在のジョブステータスです。`waiting` はキュー待ち、`processing` は処理中、`completed` は完了、`error` は失敗を示します。" + } + } + }, + "InitialAnnotationReplySettingsStatusResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "[アノテーション返信を設定](/api-reference/アノテーション管理/アノテーション返信を設定) 呼び出しから取得したジョブ ID です。" + }, + "job_status": { + "type": "string", + "description": "現在のジョブステータスです。`waiting` はキュー待ち、`processing` は処理中、`completed` は完了、`error` は失敗を示します。" + }, + "error_msg": { + "type": "string", + "description": "ジョブが失敗した理由を説明するエラーメッセージです。`job_status` が `error` でない場合は空文字列です。" + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ワークフローの実行が開始されました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ワークフロー実行 ID です。" + }, + "workflow_id": { + "type": "string", + "description": "関連するワークフロー ID です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "このワークフロー実行の入力変数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タイムスタンプ（Unix エポック秒）です。" + }, + "reason": { + "type": "string", + "description": "ワークフロー開始の理由です。`initial` は初回開始、`resumption` は一時停止後の再開（例：人的介入後）を示します。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ワークフローの実行が完了しました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ワークフロー実行 ID です。" + }, + "workflow_id": { + "type": "string", + "description": "関連するワークフロー ID です。" + }, + "status": { + "type": "string", + "description": "実行ステータスです。`running` は進行中、`succeeded` は成功、`failed` は失敗、`stopped` は手動停止、`partial-succeeded` は部分完了、`paused` は人的介入待ちを示します。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ワークフローの出力データです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "実行が失敗した場合のエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "description": "合計実行時間（秒）です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合計トークン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行された合計ステップ数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タイムスタンプ（Unix エポック秒）です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "終了タイムスタンプ（Unix エポック秒）です。" + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "実行中の例外数です。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "ワークフロー実行中に生成されたファイルです。" + } + } + } + } + } + ] + }, + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ノードの実行が開始されました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ノード実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワークフローグラフ内のノード ID です。" + }, + "node_type": { + "type": "string", + "description": "ノードタイプ（例：`llm`、`knowledge-retrieval`、`code`）です。" + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "実行インデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノードの ID です。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノードの入力データです。簡略化された API レスポンスでは `null` の場合があります。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タイムスタンプ（Unix エポック秒）です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "追加メタデータです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "このノードがイテレーション内で実行される場合のイテレーション ID です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "このノードがループ内で実行される場合のループ ID です。" + } + } + } + } + } + ] + }, + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ノードの実行が完了しました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ノード実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワークフローグラフ内のノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "実行インデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノードの ID です。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノードの入力データです。簡略化された API レスポンスでは `null` の場合があります。" + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノードの処理データです。簡略化された API レスポンスでは `null` の場合があります。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノードの出力データです。簡略化された API レスポンスでは `null` の場合があります。" + }, + "status": { + "type": "string", + "description": "ノードの実行ステータスです。`running` は進行中、`succeeded` は成功、`failed` は失敗、`exception` は例外発生を示します。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ノードが失敗した場合のエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "description": "ノードの実行時間（秒）です。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "実行メタデータ（例：トークン使用量、モデル情報）です。簡略化された API レスポンスでは `null` の場合があります。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タイムスタンプ（Unix エポック秒）です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "終了タイムスタンプ（Unix エポック秒）です。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "このノードで生成されたファイルです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "このノードがイテレーション内で実行される場合のイテレーション ID です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "このノードがループ内で実行される場合のループ ID です。" + } + } + } + } + } + ] + }, + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ノードのリトライ回数です。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ノード実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワークフローグラフ内のノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "実行インデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノードの ID です。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノードの入力データです。" + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノードの処理データです。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノードの出力データです。" + }, + "status": { + "type": "string", + "description": "ノードの実行ステータスです。`running` は進行中、`succeeded` は成功、`failed` は失敗、`exception` は例外発生を示します。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "このリトライのエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "description": "この試行の実行時間（秒）です。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "実行メタデータです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タイムスタンプ（Unix エポック秒）です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "終了タイムスタンプ（Unix エポック秒）です。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "このリトライ中に生成されたファイルです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "イテレーション ID（該当する場合）です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "ループ ID（該当する場合）です。" + }, + "retry_index": { + "type": "integer", + "description": "リトライ回数インデックス、`0` から開始します。" + } + } + } + } + } + ] + }, + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "イテレーションループが開始されました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "イテレーション実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "イテレーションノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "イテレーションノードのタイトルです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タイムスタンプ（Unix エポック秒）です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "追加メタデータです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "イテレーションのメタデータです。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "イテレーションの入力データです。" + } + } + } + } + } + ] + }, + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "イテレーションが次の項目に進みました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "イテレーション実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "イテレーションノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "イテレーションノードのタイトルです。" + }, + "index": { + "type": "integer", + "description": "現在のイテレーションインデックス（0 始まり）です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "タイムスタンプ（Unix エポック秒）です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "追加メタデータです。" + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "イテレーションループが完了しました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "イテレーション実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "イテレーションノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "イテレーションノードのタイトルです。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "イテレーションの出力データです。" + }, + "status": { + "type": "string", + "description": "イテレーションの実行ステータスです。`running` は進行中、`succeeded` は成功、`failed` は失敗、`exception` は例外発生を示します。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "イテレーションが失敗した場合のエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "description": "イテレーションの合計時間（秒）です。" + }, + "total_tokens": { + "type": "integer", + "description": "すべてのイテレーションで消費されたトークンの合計です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タイムスタンプ（Unix エポック秒）です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "終了タイムスタンプ（Unix エポック秒）です。" + }, + "steps": { + "type": "integer", + "description": "実行されたイテレーションステップの合計数です。" + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ループが開始されました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ループ実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ループノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ループノードのタイトルです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タイムスタンプ（Unix エポック秒）です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "追加メタデータです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "ループのメタデータです。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "ループの入力データです。" + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ループが次のイテレーションに進みました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ループ実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ループノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ループノードのタイトルです。" + }, + "index": { + "type": "integer", + "description": "現在のループインデックス（0 始まり）です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "タイムスタンプ（Unix エポック秒）です。" + }, + "pre_loop_output": { + "description": "前回のループイテレーションからの出力です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "追加メタデータです。" + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ループが完了しました。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ループ実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ループノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ループノードのタイトルです。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ループの出力データです。" + }, + "status": { + "type": "string", + "description": "ループの実行ステータスです。`running` は進行中、`succeeded` は成功、`failed` は失敗、`exception` は例外発生を示します。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ループが失敗した場合のエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "description": "ループの合計実行時間（秒）です。" + }, + "total_tokens": { + "type": "integer", + "description": "すべてのループイテレーションで消費されたトークンの合計です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タイムスタンプ（Unix エポック秒）です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "終了タイムスタンプ（Unix エポック秒）です。" + }, + "steps": { + "type": "integer", + "description": "実行されたループの合計ステップ数です。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "人的介入ノードがユーザー入力を待機しています。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "レスポンス送信用のフォーム ID です。" + }, + "node_id": { + "type": "string", + "description": "人的介入ノードのノード ID です。" + }, + "node_title": { + "type": "string", + "description": "人的介入ノードのタイトルです。" + }, + "form_content": { + "type": "string", + "description": "ユーザー向けのフォーム内容/説明です。" + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "フォーム入力フィールドの定義です。" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "利用可能なユーザーアクションです。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "フォーム送信認証用のトークンです。" + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "フォームが期限切れになる Unix タイムスタンプです。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "このワークフロー実行記録の永続的な識別子です。[ワークフロー実行詳細を取得](/api-reference/ワークフロー/ワークフロー実行詳細を取得) と組み合わせて、実行後に結果を取得します。" + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "一時停止中のノード ID のリストです。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "一時停止時の部分的な出力です。" + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "一時停止の理由です。" + }, + "status": { + "type": "string", + "description": "ワークフローの実行ステータスです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合計経過時間（秒）です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合計トークン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行された合計ステップ数です。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "フォーム送信後のレンダリングされた内容です。" + }, + "action_id": { + "type": "string", + "description": "実行されたアクションの ID です。" + }, + "action_text": { + "type": "string", + "description": "実行されたアクションのテキストです。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワークフロー実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "フォームが期限切れになった Unix タイムスタンプです。" + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ワークフロー内のエージェントノードからのエージェントログです。", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "ノード実行 ID です。" + }, + "id": { + "type": "string", + "description": "ログエントリ ID です。" + }, + "label": { + "type": "string", + "description": "ログエントリのラベルです。" + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "ネストされたエントリの親ログエントリ ID です。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "エラーメッセージ（該当する場合）です。" + }, + "status": { + "type": "string", + "description": "ログエントリのステータスです。" + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "ログエントリのデータです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "追加メタデータです。" + }, + "node_id": { + "type": "string", + "description": "ワークフローグラフ内のノード ID です。" + } + } + } + } + } + ] + }, + "StreamEventChatTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "テキスト内容のチャンクです。" + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "ワークフロー内のテキスト変数のソースパスです。" + } + } + } + } + } + ] + }, + "StreamEventChatTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "置換テキスト内容です。" + } + } + } + } + } + ] + }, + "WorkflowRunDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワークフロー実行 ID です。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "ワークフローの実行ステータスです。`running` は実行中、`succeeded` は正常完了、`failed` は実行エラー、`stopped` は手動停止、`partial-succeeded` は一部のノードが成功し他が失敗、`paused` は人的介入待ちを示します。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "ワークフロー実行の入力変数です。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ワークフローからの出力データです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワークフローが失敗した場合のエラーメッセージです。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワークフローの合計ステップ数です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合計トークン数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワークフロー実行が作成された Unix タイムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワークフロー実行が完了した Unix タイムスタンプです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "合計経過時間（秒）です。" + } + } + }, + "WorkflowLogsResponse": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "description": "現在のページ番号です。" + }, + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "ログエントリの合計数です。" + }, + "has_more": { + "type": "boolean", + "description": "さらにページがあるかどうかです。" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "ワークフローログエントリのリストです。" + } + } + }, + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ログエントリ ID です。" + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "ワークフロー実行のソース（例：`service-api`）です。" + }, + "created_by_role": { + "type": "string", + "description": "作成者のロール（例：`end_user`、`account`）です。" + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "管理者ユーザーが作成した場合のアカウント詳細です。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "アカウント ID。" + }, + "name": { + "type": "string", + "description": "アカウント表示名。" + }, + "email": { + "type": "string", + "description": "アカウントメールアドレス。" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ログエントリが作成された Unix タイムスタンプです。" + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ログエントリの追加詳細です。" + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワークフロー実行 ID です。" + }, + "version": { + "type": "string", + "description": "ワークフローバージョン識別子です。" + }, + "status": { + "type": "string", + "description": "ワークフローの実行ステータスです。`running` は実行中、`succeeded` は正常完了、`failed` は実行エラー、`stopped` は手動停止、`partial-succeeded` は一部のノードが成功し他が失敗、`paused` は人的介入待ちを示します。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワークフローが失敗した場合のエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合計経過時間（秒）です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合計トークン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワークフローの合計ステップ数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワークフロー実行が作成された Unix タイムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワークフロー実行が完了した Unix タイムスタンプです。" + }, + "exceptions_count": { + "type": "integer", + "description": "実行中に発生した例外の数です。" + }, + "triggered_from": { + "type": "string", + "description": "ワークフロー実行をトリガーしたソースです。`debugging` はエディタからのテスト実行、`app` は API またはアプリからの実行を示します。" + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "エンドユーザー ID。" + }, + "type": { + "type": "string", + "description": "エンドユーザーの種類です。" + }, + "is_anonymous": { + "type": "boolean", + "description": "エンドユーザーが匿名かどうかです。" + }, + "session_id": { + "type": "string", + "description": "セッション識別子です。" + } + } + }, + "HumanInputContent": { + "type": "object", + "description": "人的介入ノードからの実行コンテンツです。フォーム定義と送信データを含みます。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "このコンテンツが属するワークフロー実行の ID です。" + }, + "submitted": { + "type": "boolean", + "description": "人的介入フォームが送信されたかどうかです。" + }, + "type": { + "type": "string", + "description": "`human_input` は人的介入コンテンツを示します。" + }, + "form_definition": { + "nullable": true, + "description": "人的介入ノードからのフォーム定義です。コンテンツが送信レスポンスを表す場合は `null` です。", + "$ref": "#/components/schemas/HumanInputFormDefinition" + }, + "form_submission_data": { + "nullable": true, + "description": "送信されたフォームデータです。フォームがまだ送信されていない場合は `null` です。", + "$ref": "#/components/schemas/HumanInputFormSubmissionData" + } + } + }, + "HumanInputFormDefinition": { + "type": "object", + "description": "人的介入ノードによってレンダリングされる人的介入フォームの定義です。", + "properties": { + "form_id": { + "type": "string", + "description": "フォームの一意識別子です。" + }, + "node_id": { + "type": "string", + "description": "このフォームを生成した人的介入ノードの ID です。" + }, + "node_title": { + "type": "string", + "description": "人的介入ノードのタイトルです。" + }, + "form_content": { + "type": "string", + "description": "フォームと共に表示される Markdown またはテキストコンテンツです。" + }, + "inputs": { + "type": "array", + "description": "フォーム内の入力フィールドです。", + "items": { + "$ref": "#/components/schemas/FormInput" + } + }, + "actions": { + "type": "array", + "description": "フォームで利用可能なアクションボタンです。", + "items": { + "$ref": "#/components/schemas/UserAction" + } + }, + "display_in_ui": { + "type": "boolean", + "description": "フォームを UI に表示するかどうかです。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "フォーム送信認証用のトークンです。" + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "出力変数名をキーとする、フォーム入力の解決済みデフォルト値です。" + }, + "expiration_time": { + "type": "integer", + "description": "フォームが期限切れになる Unix タイムスタンプです。" + } + } + }, + "HumanInputFormSubmissionData": { + "type": "object", + "description": "送信された人的介入フォームからのデータです。", + "properties": { + "node_id": { + "type": "string", + "description": "人的介入ノードの ID です。" + }, + "node_title": { + "type": "string", + "description": "人的介入ノードのタイトルです。" + }, + "rendered_content": { + "type": "string", + "description": "フォーム送信のレンダリングされた内容です。" + }, + "action_id": { + "type": "string", + "description": "クリックされたアクションボタンの ID です。" + }, + "action_text": { + "type": "string", + "description": "クリックされたアクションボタンの表示テキストです。" + } + } + }, + "FormInput": { + "type": "object", + "description": "フォーム入力フィールドの定義です。", + "properties": { + "type": { + "type": "string", + "description": "`text_input` は単一行テキスト、`paragraph` は複数行テキストです。" + }, + "output_variable_name": { + "type": "string", + "description": "入力値が格納される変数名です。" + }, + "default": { + "nullable": true, + "description": "この入力のデフォルト値設定です。", + "$ref": "#/components/schemas/FormInputDefault" + } + } + }, + "FormInputDefault": { + "type": "object", + "description": "フォーム入力のデフォルト値設定です。", + "properties": { + "type": { + "type": "string", + "description": "`variable` はワークフロー変数からの動的な値、`constant` は静的な値です。" + }, + "selector": { + "type": "array", + "items": { + "type": "string" + }, + "description": "`type` が `variable` の場合の変数セレクターパスです。" + }, + "value": { + "type": "string", + "description": "`type` が `constant` の場合の静的値。" + } + } + }, + "UserAction": { + "type": "object", + "description": "人的介入フォーム上のアクションボタンです。", + "properties": { + "id": { + "type": "string", + "description": "アクションの一意識別子です。" + }, + "title": { + "type": "string", + "description": "ボタンの表示テキストです。" + }, + "button_style": { + "type": "string", + "description": "`primary`, `default`, `accent`, or `ghost`." + } + } + } } }, "tags": [ - { "name": "チャットメッセージ", "description": "チャットメッセージとインタラクションに関連する操作。" }, - { "name": "ファイル操作", "description": "ファイルアップロードとプレビューに関連する操作。" }, - { "name": "エンドユーザー", "description": "エンドユーザー情報に関連する操作。" }, - { "name": "メッセージフィードバック", "description": "ユーザーメッセージへのフィードバック操作。" }, - { "name": "会話管理", "description": "会話セッションの管理に関連する操作。" }, - { "name": "音声・テキスト変換", "description": "テキストから音声へ、音声からテキストへの変換操作。" }, - { "name": "アプリケーション設定", "description": "アプリケーション設定と情報の取得に関連する操作。" } + { + "name": "チャットメッセージ", + "description": "チャットメッセージとインタラクションに関連する操作です。" + }, + { + "name": "ファイル操作", + "description": "ファイルのアップロードとプレビューの操作です。" + }, + { + "name": "エンドユーザー", + "description": "エンドユーザー情報に関連する操作です。" + }, + { + "name": "メッセージフィードバック", + "description": "ユーザーフィードバックの操作です。" + }, + { + "name": "会話管理", + "description": "会話管理に関連する操作です。" + }, + { + "name": "音声・テキスト変換", + "description": "テキスト読み上げと音声認識の操作です。" + }, + { + "name": "アプリケーション設定", + "description": "アプリケーション設定と情報を取得する操作です。" + }, + { + "name": "アノテーション管理", + "description": "ダイレクト返信用のアノテーション管理に関連する操作です。" + }, + { + "name": "ワークフロー実行", + "description": "ワークフロー実行の詳細とログに関連する操作です。" + } ] -} \ No newline at end of file +} diff --git a/ja/api-reference/openapi_completion.json b/ja/api-reference/openapi_completion.json index ad694820..05988e33 100644 --- a/ja/api-reference/openapi_completion.json +++ b/ja/api-reference/openapi_completion.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "Completion アプリ API", - "description": "テキスト生成アプリケーションはセッションレスをサポートし、翻訳、記事作成、要約AI等に最適です。", + "description": "テキスト生成アプリケーションはセッションなしで動作し、翻訳、記事作成、要約 AI などに最適です。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API のベースURL。 {api_base_url} をアプリケーション提供の実際の API ベースURLに置き換えてください。", + "description": "テキスト生成アプリ API のベース URL です。{api_base_url} をアプリケーションに提供された実際の API ベース URL に置き換えてください。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "実際の API ベースURL" + "description": "API の実際のベース URL" } } } @@ -25,25 +25,48 @@ "paths": { "/completion-messages": { "post": { - "summary": "完了メッセージの作成", + "summary": "完了メッセージを送信", "description": "テキスト生成アプリケーションにリクエストを送信します。", "operationId": "createCompletionMessageJp", - "tags": ["完了メッセージ"], + "tags": [ + "完了メッセージ" + ], "requestBody": { - "description": "完了メッセージを作成するためのリクエストボディ。", + "description": "テキスト生成メッセージを作成するためのリクエストボディ。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CompletionRequestJp" + "$ref": "#/components/schemas/CompletionRequest" }, "examples": { - "streaming_example_jp": { - "summary": "ストリーミングモードの例", + "streaming_example": { + "summary": "リクエスト例 - ストリーミングモード", "value": { - "inputs": {"query": "こんにちは、世界！"}, + "inputs": { + "city": "San Francisco" + }, + "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", - "user": "jp_user_123" + "user": "abc-123", + "files": [ + { + "type": "image", + "transfer_method": "remote_url", + "url": "https://cloud.dify.ai/logo/logo-site.png" + } + ] + } + }, + "blocking_example": { + "summary": "リクエスト例 - ブロッキングモード", + "value": { + "inputs": { + "city": "New York" + }, + "query": "Summarize the following text: ...", + "response_mode": "blocking", + "user": "def-456" } } } @@ -52,287 +75,2467 @@ }, "responses": { "200": { - "description": "リクエスト成功。レスポンスのコンテントタイプと構造はリクエストの `response_mode` パラメータに依存します。\n- `response_mode` が `blocking` の場合、`application/json` で `CompletionResponseJp` オブジェクトを返します。\n- `response_mode` が `streaming` の場合、`text/event-stream` で `ChunkCompletionEventJp` のストリームを返します。", + "description": "リクエスト成功。コンテンツタイプと構造はリクエストの `response_mode` パラメータに依存します。\n\n- `response_mode` が `blocking` の場合、 `application/json` で `CompletionResponse` オブジェクトを返します。\n- `response_mode` が `streaming` の場合、 `text/event-stream` で `ChunkCompletionEvent` オブジェクトのストリームを返します。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CompletionResponseJp" + "$ref": "#/components/schemas/CompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "レスポンス例 - ブロッキングモード", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "mode": "completion", + "answer": "Hello World!...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + } + }, + "created_at": 1705407629 + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "SSE (Server-Sent Events) のストリーム。各イベントは 'data: ' で始まり、'\\n\\n' で終わるJSONオブジェクトです。詳細は `ChunkCompletionEventJp` を参照してください。" + "description": "サーバー送信イベント (SSE) のストリームです。各イベントは `data: ` プレフィックス付きの JSON オブジェクトで、2 つの改行で終了します。\n\n**SSE パースガイド：**各イベントは `data: ` プレフィックス付きの JSON オブジェクトの行で、`\\n\\n` で終了します。JSON をパースする前に `data: ` プレフィックスを除去してください。JSON 内の `event` フィールドがイベントタイプを決定します。終了イベント（`message_end`、`error` など）を受信するとストリームは終了します。`ping` イベント（10 秒ごとに接続維持のために送信）は無視してください。ストリーム内でエラーイベントが発生しても HTTP ステータスコードは常に `200` です。" + }, + "examples": { + "streamingResponse": { + "summary": "レスポンス例 - ストリーミングモード", + "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n" + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestGenericJp" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } - } - } - }, - "/files/upload": { - "post": { - "summary": "ファイルアップロード", - "description": "メッセージ送信時に使用するファイル（現在は画像のみ対応）をアップロードし、画像とテキストのマルチモーダルな理解を可能にします。png、jpg、jpeg、webp、gif形式に対応しています。アップロードされたファイルは、現在のエンドユーザーのみが使用できます。", - "operationId": "uploadCompletionFileJp", - "tags": ["ファイル操作"], - "requestBody": { - "description": "ファイルアップロードリクエスト。`multipart/form-data` 形式が必要です。", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { "type": "string", "format": "binary", "description": "アップロードするファイル。" }, - "user": { "type": "string", "description": "開発者のルールで定義されたユーザー識別子。アプリケーション内で一意である必要があります。" } - } - } - } - } - }, - "responses": { - "200": { "description": "ファイルアップロード成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } }, - "201": { "description": "ファイル作成成功（代替成功コード）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } }, - "400": { "$ref": "#/components/responses/BadRequestFileJp" }, - "413": { "$ref": "#/components/responses/FileTooLargeJp" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileJp" }, - "503": { "$ref": "#/components/responses/S3ErrorFileJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "エンドユーザー取得", - "description": "IDでエンドユーザーを取得します。\n\n他のAPIがエンドユーザーID（例：ファイルアップロードの `created_by`）を返す場合に利用できます。", - "operationId": "getEndUserCompletionJp", - "tags": ["エンドユーザー"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "エンドユーザーID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "responses": { - "200": { - "description": "エンドユーザーの取得に成功しました。", + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルは利用できません。\n- `completion_request_error` : テキスト生成に失敗しました。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailJp" } + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + "429": { + "description": "`too_many_requests` : このアプリケーションへの同時リクエストが多すぎます。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } } } }, "/completion-messages/{task_id}/stop": { "post": { - "summary": "生成の停止", - "description": "完了メッセージの生成を停止します。ストリーミングモードでのみサポートされています。", + "summary": "生成を停止", + "description": "テキスト生成メッセージ生成タスクを停止します。`streaming` モードでのみサポートされています。", "operationId": "stopCompletionGenerationJp", - "tags": ["完了メッセージ"], + "tags": [ + "完了メッセージ" + ], "parameters": [ - { "name": "task_id", "in": "path", "required": true, "description": "タスクID、ストリーミングチャンクの返信から取得可能。", "schema": { "type": "string", "format": "uuid" } } + { + "name": "task_id", + "in": "path", + "required": true, + "description": "タスク ID です。[完了メッセージを送信](/api-reference/完了メッセージ/完了メッセージを送信) API のストリーミングチャンクレスポンスから取得できます。", + "schema": { + "type": "string" + } + } ], "requestBody": { "required": true, - "content": { "application/json": { "schema": { "type": "object", "required": ["user"], "properties": { "user": { "type": "string", "description": "ユーザー識別子。メッセージ送信インターフェースで渡されたユーザーと一致する必要があります。" } } } } } + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "user" + ], + "properties": { + "user": { + "type": "string", + "description": "ユーザー識別子。メッセージ送信インターフェースで渡された user と一致する必要があります。" + } + } + }, + "examples": { + "example": { + "summary": "リクエスト例", + "value": { + "user": "abc-123" + } + } + } + } + } }, - "responses": { "200": { "$ref": "#/components/responses/SuccessResultJp" } } + "responses": { + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } } }, "/messages/{message_id}/feedbacks": { "post": { - "summary": "メッセージフィードバック", - "description": "エンドユーザーはフィードバックメッセージを提供でき、アプリケーション開発者が期待される出力を最適化するのに役立ちます。", "operationId": "postCompletionMessageFeedbackJp", - "tags": ["メッセージフィードバック"], - "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "メッセージID。", "schema": { "type": "string", "format": "uuid" } } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestJp" } } } }, - "responses": { "200": { "$ref": "#/components/responses/SuccessResultJp" } } + "tags": [ + "メッセージフィードバック" + ], + "summary": "メッセージフィードバックを送信", + "description": "メッセージに対するフィードバックを送信します。エンドユーザーはメッセージを `like` または `dislike` で評価でき、任意でテキストフィードバックを提供できます。`rating` に `null` を渡すと、以前送信したフィードバックを取り消せます。", + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "メッセージ ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "リクエスト例", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : メッセージが存在しません。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + } + } } }, "/app/feedbacks": { "get": { - "summary": "アプリのメッセージの「いいね」とフィードバックを取得", - "description": "アプリのエンドユーザーからのフィードバックや「いいね」を取得します。", "operationId": "getAppFeedbacksCompletionJp", - "tags": ["メッセージフィードバック"], - "parameters": [ - { "name": "page", "in": "query", "description": "（任意）ページ番号。デフォルト値：1。", "schema": { "type": "integer", "default": 1 } }, - { "name": "limit", "in": "query", "description": "（任意）1ページあたりの件数。デフォルト値：20。", "schema": { "type": "integer", "default": 20 } } + "tags": [ + "メッセージフィードバック" ], - "responses": { "200": { "description": "フィードバックリストの取得成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseJp" } } } } } + "summary": "アプリのフィードバック一覧を取得", + "description": "このアプリケーションのメッセージに対して送信されたすべてのフィードバックのページネーション付きリストを取得します。エンドユーザーと管理者のフィードバックの両方が含まれます。", + "parameters": [ + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1ページあたりのレコード数。", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } + } + ], + "responses": { + "200": { + "description": "アプリケーションフィードバックのリスト。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "rating": "like", + "content": "The response accurately answered my question about product specifications.", + "from_source": "user", + "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "from_account_id": null, + "created_at": "2025-01-16T14:30:29Z", + "updated_at": "2025-01-16T14:30:29Z" + }, + { + "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", + "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", + "rating": "dislike", + "content": "The answer was too vague and did not address the specific pricing question.", + "from_source": "user", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", + "from_account_id": null, + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" + } + ] + } + } + } + } + } + } + } + } + }, + "/files/upload": { + "post": { + "operationId": "uploadCompletionFileJp", + "tags": [ + "ファイル操作" + ], + "summary": "ファイルをアップロード", + "description": "メッセージ送信時に使用するファイルをアップロードします。画像、ドキュメント、音声、動画のマルチモーダル理解が可能です。アップロードされたファイルは現在のエンドユーザーのみが使用できます。", + "requestBody": { + "description": "ファイルアップロードリクエスト。multipart/form-data 形式が必要です。", + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "アップロードするファイル。サポートされるタイプには画像、ドキュメント、音声、動画が含まれます。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。開発者のルールで定義され、アプリケーション内で一意である必要があります。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "ファイルが正常にアップロードされました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : リクエストにファイルが提供されていません。\n- `too_many_files` : 1 回のリクエストにつき 1 ファイルのみ許可されています。\n- `filename_not_exists_error` : アップロードされたファイルにファイル名がありません。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : ファイルサイズの上限を超えています。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 許可されていないファイルタイプです。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { + "get": { + "operationId": "previewCompletionFileJa", + "tags": [ + "ファイル操作" + ], + "summary": "ファイルをダウンロード", + "description": "以前[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API 経由でアップロードされたファイルをプレビューまたはダウンロードします。ファイルは、リクエスト元のアプリケーション内のメッセージに属する場合のみアクセスできます。", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "プレビューするファイルの一意の識別子です。[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API のレスポンスから取得します。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "`true` の場合、ブラウザでプレビューする代わりにファイルを添付ファイルとして強制ダウンロードします。", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子。エンドユーザーのコンテキストに使用されます。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "生のファイルコンテンツを返します。`Content-Type` ヘッダーはファイルの MIME タイプに設定されます。`as_attachment` が `true` の場合、ファイルは `Content-Disposition: attachment` としてダウンロード形式で返されます。", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : リクエストされたファイルへのアクセスが拒否されました。", + "content": { + "application/json": { + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : リクエストされたファイルが見つかりません。", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "operationId": "getEndUserCompletionJp", + "tags": [ + "エンドユーザー" + ], + "summary": "エンドユーザー取得", + "description": "ID を指定してエンドユーザーを取得します。他の API がエンドユーザー ID を返す場合（例：[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード)の `created_by`）に便利です。", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "エンドユーザー ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "エンドユーザーを正常に取得しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "レスポンス例", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : エンドユーザーが見つかりません。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "completionAudioToTextJa", + "tags": [ + "音声・テキスト変換" + ], + "summary": "音声をテキストに変換", + "description": "音声ファイルをテキストに変換します。サポートされる形式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファイルサイズの上限は `30 MB` です。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "音声からテキストへの変換に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "レスポンス例", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `no_audio_uploaded` : 音声ファイルがアップロードされていません。\n- `provider_not_support_speech_to_text` : モデルプロバイダーが音声認識をサポートしていません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルはこの操作をサポートしていません。\n- `completion_request_error` : 音声認識リクエストに失敗しました。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音声ファイルサイズが上限を超えています。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 許可されていない音声タイプです。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } } }, "/text-to-audio": { "post": { - "summary": "テキストから音声", - "description": "テキストを音声に変換します。", "operationId": "textToAudioCompletionJp", - "tags": ["音声変換"], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToAudioRequestJp" } } } }, + "tags": [ + "音声・テキスト変換" + ], + "summary": "テキストを音声に変換", + "description": "テキストを音声に変換します。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "リクエスト例", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, "responses": { "200": { - "description": "音声ファイル生成成功。", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, - "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } + "description": "生成された音声ファイルを返します。`Content-Type` ヘッダーは音声の MIME タイプ（例：`audio/wav`、`audio/mp3`）に設定されます。`streaming` が `true` の場合、音声はチャンク転送エンコーディングでストリーミングされます。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルはこの操作をサポートしていません。\n- `completion_request_error` : テキスト読み上げリクエストに失敗しました。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } } } } }, "/info": { "get": { - "summary": "アプリケーションの基本情報を取得", "operationId": "getCompletionAppInfoJp", - "tags": ["アプリケーション情報"], - "responses": { "200": { "description": "アプリケーション基本情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリケーションの基本情報を取得", + "description": "このアプリケーションの基本情報（名前、説明、タグ、モード）を取得します。", + "responses": { + "200": { + "description": "アプリケーションの基本情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "レスポンス例", + "value": { + "name": "My Completion App", + "description": "便利なカスタマーサービスチャットボット。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "completion", + "author_name": "Dify Team" + } + } + } + } + } + } + } } }, "/parameters": { "get": { - "summary": "アプリケーションのパラメータ情報を取得", "operationId": "getCompletionAppParametersJp", - "tags": ["アプリケーション情報"], - "responses": { "200": { "description": "アプリケーションパラメータ情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionAppParametersResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリケーションのパラメータ情報を取得", + "description": "アプリケーションの入力フォーム設定（機能スイッチ、入力パラメータ名、タイプ、デフォルト値）を取得します。", + "responses": { + "200": { + "description": "アプリケーションパラメータ情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompletionAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "レスポンス例", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getCompletionAppMetaJa", + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリケーションのメタ情報を取得", + "description": "このアプリケーションのメタデータ（ツールアイコンやその他の設定詳細）を取得します。", + "responses": { + "200": { + "description": "アプリケーションのメタ情報を正常に取得しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "レスポンス例", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } } }, "/site": { "get": { - "summary": "アプリのWebApp設定を取得", "operationId": "getCompletionWebAppSettingsJp", - "tags": ["アプリケーション情報"], - "responses": { "200": { "description": "WebApp設定。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリの WebApp 設定を取得", + "description": "このアプリケーションの WebApp 設定（サイト設定、テーマ、カスタマイズオプション）を取得します。", + "responses": { + "200": { + "description": "アプリケーションの WebApp 設定。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "レスポンス例", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "便利なカスタマーサービスチャットボット。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このアプリケーションのサイトが見つからないか、ワークスペースがアーカイブされています。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key認証。すべてのAPIリクエストで、`Authorization` HTTPヘッダーに `Bearer {API_KEY}` の形式でAPIキーを含めてください。APIキーの漏洩を避けるため、サーバーサイドでの保存を強く推奨します。" } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 認証です。すべての API リクエストにおいて、`Authorization` HTTP ヘッダーに `Bearer ` プレフィックスを付けた API Key を含めてください。例：`Authorization: Bearer {API_KEY}`。**API Key はサーバーサイドに保存し、クライアントサイドで共有・保存しないことを強く推奨します。API Key の漏洩は深刻な結果につながる可能性があります。**" + } }, "responses": { - "BadRequestGenericJp": { "description": "リクエストパラメータエラー。エラーコード例: invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "ConversationNotFoundJp": { "description": "会話が存在しません。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "InternalServerErrorJp": { "description": "内部サーバーエラー。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "BadRequestFileJp": { "description": "ファイル操作リクエストエラー。エラーコード例: no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "FileTooLargeJp": { "description": "ファイルが大きすぎます (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "UnsupportedFileTypeFileJp": { "description": "サポートされていないファイルタイプです (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "S3ErrorFileJp": { "description": "S3ストレージサービスエラー。エラーコード例: s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "SuccessResultJp": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "EndUserNotFoundJp": { "description": "エンドユーザーが見つかりません。エラーコード：`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } } + "SuccessResult": { + "description": "操作が成功しました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "結果ステータス。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "CompletionRequestJp": { - "type": "object", "required": ["inputs"], + "CompletionRequest": { + "type": "object", + "required": [ + "inputs", + "user" + ], "properties": { - "inputs": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "入力テキスト、処理される内容。" } }, "additionalProperties": true, "description": "アプリで定義された各種変数値を入力。少なくとも1つのキー/値ペアが必要。" }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "レスポンス返却モード。streaming (推奨): SSEによるタイプライター風出力。blocking: 実行完了後に結果返却 (Cloudflare 100秒制限あり)。" }, - "user": { "type": "string", "description": "ユーザー識別子。アプリケーション内で開発者が一意に定義。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectJp" }, "description": "(任意) ファイルリスト。モデルがVision機能をサポートしている場合のみ利用可能。" } + "inputs": { + "type": "object", + "description": "アプリで定義されたさまざまな変数の値を入力できます。キーと値のペアを含み、各キーは特定の変数に対応し、各値はその変数の具体的な値です。アプリが期待する変数名と型については、[アプリケーションのパラメータ情報を取得](/api-reference/アプリケーション設定/アプリケーションのパラメータ情報を取得) レスポンスの `user_input_form` フィールドを参照してください。", + "additionalProperties": true + }, + "query": { + "type": "string", + "default": "", + "description": "処理対象の入力テキストです。これはレガシーパラメータであり、新しいアプリではクエリを `inputs` オブジェクト内で渡す必要があります。" + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "レスポンスの返却モード。`streaming`（推奨）は SSE を使用します。`blocking` は完了後に返却します（長時間の処理では中断される場合があります）。Cloudflare のタイムアウトは `100 s` です。省略した場合、デフォルトでブロッキングモードになります。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。アプリケーション内で一意です。この識別子はデータアクセスの範囲を制限します。メッセージとファイルは同じ `user` 値でクエリした場合のみ表示されます。" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + }, + "description": "マルチモーダル理解用のファイルリストです。画像、ドキュメント、音声、動画を含みます。ローカルファイルを添付するには、まず [ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) でアップロードし、返された `id` を `upload_file_id` として `transfer_method: local_file` で使用します。" + } } }, - "InputFileObjectJp": { - "type": "object", "required": ["type", "transfer_method"], + "InputFileObject": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], "properties": { - "type": { "type": "string", "enum": ["image"], "description": "サポートされるタイプ：`image`（現在は画像タイプのみサポート）。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "転送方法。remote_url は画像URL / local_file はファイルアップロード用" }, - "url": { "type": "string", "format": "url", "description": "画像URL（転送方法が remote_url の場合）" }, - "upload_file_id": { "type": "string", "format": "uuid", "description": "アップロードされたファイルID、事前にファイルアップロードAPIで取得する必要があります（転送方法が local_file の場合）" } + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "ファイルタイプ。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "転送方法です。ファイル URL の場合は `remote_url`、アップロードファイルの場合は `local_file` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファイル URL（`transfer_method` が `remote_url` の場合）です。" + }, + "upload_file_id": { + "type": "string", + "description": "事前に [ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API でアップロードして取得したファイル ID です（`transfer_method` が `local_file` の場合に使用）。" + } }, "anyOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } + "properties": { + "transfer_method": { + "enum": [ + "remote_url" + ] + }, + "url": { + "type": "string", + "format": "url" + } }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "required": [ + "url" + ], + "not": { + "required": [ + "upload_file_id" + ] + } }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format": "uuid" } + "properties": { + "transfer_method": { + "enum": [ + "local_file" + ] + }, + "upload_file_id": { + "type": "string" + } }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "required": [ + "upload_file_id" + ], + "not": { + "required": [ + "url" + ] + } } ] }, - "CompletionResponseJp": { - "type": "object", "description": "ブロッキングモードでのアプリの完全な結果。", - "properties": { - "event": { "type": "string", "description": "イベントタイプ、通常 'message'。(MarkdownではChatCompletionResponseで 'chat' とあったが、Completionの文脈では 'completion' or 'message' が一般的。blocking example に合わせて 'message' を使用)" }, - "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, - "mode": { "type": "string", "description": "アプリモード。ブロッキングモードの例では 'completion'、Markdown本文では 'chat' と記載。ここでは 'completion' を採用。" }, - "answer": { "type": "string", "description": "完全な応答内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataJp" }, - "created_at": { "type": "integer", "format": "int64", "description": "メッセージ作成タイムスタンプ。" } - } - }, - "ResponseMetadataJp": { "type": "object", "description": "メタデータ。", "properties": { "usage": { "$ref": "#/components/schemas/UsageJp" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJp" }, "description": "引用と帰属のリスト。" } } }, - "ChunkCompletionEventJp": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], "description": "イベントタイプ。" } }, - "discriminator": { "propertyName": "event", "mapping": { "message": "#/components/schemas/StreamEventMessageJp", "message_end": "#/components/schemas/StreamEventMessageEndJp", "tts_message": "#/components/schemas/StreamEventTtsMessageJp", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndJp", "message_replace": "#/components/schemas/StreamEventMessageReplaceJp", "error": "#/components/schemas/StreamEventErrorJp", "ping": "#/components/schemas/StreamEventPingJp" } } - }, - "StreamEventBaseCompletionJp": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } }, - "StreamEventMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLMが返したテキストチャンクの内容。" } } } ] }, - "StreamEventMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataJp" } } } ] }, - "StreamEventTtsMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64エンコードされた音声ブロック。" } } } ] }, - "StreamEventTtsMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空文字列。" } } } ] }, - "StreamEventMessageReplaceJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "置換内容。" } } } ] }, - "StreamEventErrorJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["status", "code", "message"], "properties": { "status": { "type": "integer", "description": "HTTPステータスコード。" }, "code": { "type": "string", "description": "エラーコード。" }, "message": { "type": "string", "description": "エラーメッセージ。" } } } ] }, - "StreamEventPingJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "type": "object", "description": "接続維持のためのPingイベント。" } ] }, - "UsageJp": { "type": "object", "description": "モデル使用情報。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceJp": { "type": "object", "description": "引用と帰属の情報。", "properties": { "document_id": { "type": "string" }, "segment_id": { "type": "string" }, "score": { "type": "number" }, "content": { "type": "string" } } }, - "FileUploadResponseJp": { "type": "object", "description": "ファイルアップロード成功時のレスポンス。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "ファイル名。" }, "size": { "type": "integer", "description": "ファイルサイズ（バイト）。" }, "extension": { "type": "string", "description": "ファイル拡張子。" }, "mime_type": { "type": "string", "description": "ファイルのMIMEタイプ。" }, "created_by": { "type": "string", "format": "uuid", "description": "エンドユーザーID。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } }, - "EndUserDetailJp": { + "CompletionResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "event": { + "type": "string", + "description": "イベントタイプ。`message` に固定されています。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "リクエスト追跡および [生成を停止](/api-reference/完了メッセージ/生成を停止) API 用のタスク ID です。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "このレスポンスイベントの一意 ID です。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "一意のメッセージ ID です。フィードバックや推奨質問のエンドポイントを呼び出す際に `message_id` パラメータとして使用します。" + }, + "mode": { + "type": "string", + "description": "アプリモード、`completion` 固定です。" + }, + "answer": { + "type": "string", + "description": "完全なレスポンスコンテンツ。" + }, + "metadata": { + "type": "object", + "description": "使用量と検索リソースを含むメタデータ。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用された検索リソースのリスト。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "メッセージ作成タイムスタンプ（Unix エポック秒）。" + } } }, - "MessageFeedbackRequestJp": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "高評価 `like`, 低評価 `dislike`, 取り消し `null`。" }, "user": { "type": "string", "description": "ユーザー識別子。" }, "content": { "type": "string", "nullable": true, "description": "メッセージフィードバックの具体的な内容。" } } }, - "AppFeedbacksResponseJp": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemJp" }, "description": "このアプリの「いいね」とフィードバックの一覧。" } } }, - "FeedbackItemJp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "TextToAudioRequestJp": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "メッセージID（textより優先）。" }, "text": { "type": "string", "description": "音声生成コンテンツ。" }, "user": { "type": "string", "description": "ユーザー識別子。" } }, "description": "`user`が必須。`message_id`または`text`のいずれかを提供。" }, - "AppInfoResponseJp": { "type": "object", "description": "アプリケーションの基本情報。", "properties": { "name": { "type": "string", "description": "アプリケーションの名前。" }, "description": { "type": "string", "description": "アプリケーションの説明。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "アプリケーションのタグ。" } } }, - "CompletionAppParametersResponseJp": { "type": "object", "description": "アプリケーションのパラメータ情報。", "properties": { "opening_statement": { "type": "string", "description": "開始文。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "開始時の提案質問リスト。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "description": "回答後の提案質問。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "description": "音声からテキスト。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "description": "引用と帰属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "description": "注釈付き返信。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemJp" }, "description": "ユーザー入力フォーム設定。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "画像設定。" } }, "description": "ファイルアップロード設定。" }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer" }, "image_file_size_limit": { "type": "integer" }, "audio_file_size_limit": { "type": "integer" }, "video_file_size_limit": { "type": "integer" } }, "description": "システムパラメータ。" } } }, - "UserInputFormItemJp": { "type": "object", "description": "ユーザー入力フォームのコントロール項目。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperJp" }, { "$ref": "#/components/schemas/ParagraphControlWrapperJp" }, { "$ref": "#/components/schemas/SelectControlWrapperJp" } ] }, - "TextInputControlWrapperJp": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlJp" } }, "required":["text-input"] }, - "ParagraphControlWrapperJp": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlJp" } }, "required":["paragraph"] }, - "SelectControlWrapperJp": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlJp" } }, "required":["select"] }, - "TextInputControlJp": { "type": "object", "description": "テキスト入力コントロール。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" } } }, - "ParagraphControlJp": { "type": "object", "description": "段落テキスト入力コントロール。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" } } }, - "SelectControlJp": { "type": "object", "description": "ドロップダウンコントロール。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必须かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "オプション値。" } } }, - "WebAppSettingsResponseJp": { "type": "object", "description": "アプリケーションのWebApp設定。", "properties": { "title": { "type": "string", "description": "WebApp名。" }, "chat_color_theme": { "type": "string", "description": "チャットの色テーマ（16進数）。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "テーマ反転。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "アイコンタイプ。" }, "icon": { "type": "string", "description": "アイコン（emojiまたは画像URL）。" }, "icon_background": { "type": "string", "description": "背景色（16進数）。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "アイコンURL。" }, "description": { "type": "string", "description": "説明。" }, "copyright": { "type": "string", "description": "著作権情報。" }, "privacy_policy": { "type": "string", "description": "プライバシーポリシーリンク。" }, "custom_disclaimer": { "type": "string", "description": "カスタム免責事項。" }, "default_language": { "type": "string", "description": "デフォルト言語。" }, "show_workflow_steps": { "type": "boolean", "description": "ワークフロー詳細表示。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "WebAppアイコンを返信アイコンとして使用。" } } }, - "ErrorResponseJp": { "type": "object", "description": "エラーレスポンス。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTPステータスコード。" }, "code": { "type": "string", "nullable": true, "description": "エラーコード。" }, "message": { "type": "string", "description": "エラーメッセージ。" } } } + "ChunkCompletionEvent": { + "type": "object", + "properties": { + "event": { + "type": "string", + "enum": [ + "message", + "message_end", + "message_file", + "tts_message", + "tts_message_end", + "message_replace", + "error", + "ping" + ], + "description": "ストリーミングイベントのタイプ。" + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventMessage", + "message_end": "#/components/schemas/StreamEventMessageEnd", + "message_file": "#/components/schemas/StreamEventMessageFile", + "tts_message": "#/components/schemas/StreamEventTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", + "message_replace": "#/components/schemas/StreamEventMessageReplace", + "error": "#/components/schemas/StreamEventError", + "ping": "#/components/schemas/StreamEventPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "タスク ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "一意のメッセージ ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + } + } + }, + "StreamEventMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "LLM がテキストチャンクイベントを返します。", + "properties": { + "answer": { + "type": "string", + "description": "LLM が返したテキストチャンクのコンテンツ。" + } + } + } + ] + }, + "StreamEventMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "メッセージ終了イベント。このイベントを受信すると、ストリーミングが終了したことを意味します。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "メッセージの一意な ID。" + }, + "metadata": { + "type": "object", + "description": "使用量と検索リソースを含むメタデータ。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用された検索リソースのリスト。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } + ] + }, + "StreamEventTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリームイベント（base64 エンコード MP3）。自動再生が有効な場合に利用できます。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 エンコードされた MP3 音声チャンク。すべてのチャンクを順番にデコードして連結すると、完全な音声ファイルが生成されます。" + } + } + } + ] + }, + "StreamEventTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリーム終了イベント。", + "properties": { + "audio": { + "type": "string", + "description": "空の文字列。音声ストリームの終了を示します。" + } + } + } + ] + }, + "StreamEventMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "メッセージファイルイベント。ツールによって作成された新しいファイルです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ファイルの一意の ID。" + }, + "type": { + "type": "string", + "description": "ファイルタイプ（例：`image`）。" + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "このファイルの所有者。ここでは常に `assistant` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファイルのリモート URL。" + } + } + } + ] + }, + "StreamEventMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "メッセージコンテンツ置換イベント（例：コンテンツモデレーションによるもの）。", + "properties": { + "answer": { + "type": "string", + "description": "置換コンテンツ。" + }, + "reason": { + "type": "string", + "description": "コンテンツ置換の理由。" + } + } + } + ] + }, + "StreamEventError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ストリーミング中のエラーイベント。", + "properties": { + "status": { + "type": "integer", + "description": "HTTP ステータスコード。" + }, + "code": { + "type": "string", + "description": "エラーコード。" + }, + "message": { + "type": "string", + "description": "エラーメッセージ。" + } + } + } + ] + }, + "StreamEventPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "接続を維持するための Ping イベント。" + } + ] + }, + "Usage": { + "type": "object", + "properties": { + "prompt_tokens": { + "type": "integer", + "description": "プロンプト内のトークン数。" + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "プロンプトトークンあたりの単価。" + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "プロンプトトークンの価格単位。" + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "プロンプトトークンの合計価格。" + }, + "completion_tokens": { + "type": "integer", + "description": "補完のトークン数。" + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "補完トークンあたりの単価。" + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "補完トークンの価格単位。" + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "補完トークンの合計価格。" + }, + "total_tokens": { + "type": "integer", + "description": "使用されたトークンの合計数。" + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "すべてのトークンの合計価格。" + }, + "currency": { + "type": "string", + "description": "課金通貨。" + }, + "latency": { + "type": "number", + "format": "double", + "description": "レイテンシ（秒）。" + } + } + }, + "RetrieverResource": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "検索リソースの一意の ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "このリソースが属するメッセージの ID。" + }, + "position": { + "type": "integer", + "description": "リスト内のリソースの位置。" + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "ナレッジベース ID。" + }, + "dataset_name": { + "type": "string", + "description": "ナレッジベース名。" + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "ドキュメント ID。" + }, + "document_name": { + "type": "string", + "description": "ドキュメント名。" + }, + "data_source_type": { + "type": "string", + "description": "データソースのタイプ。" + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "ドキュメント内の特定のチャンクの ID。" + }, + "score": { + "type": "number", + "format": "float", + "description": "リソースの関連性スコア。" + }, + "hit_count": { + "type": "integer", + "description": "このチャンクがヒットした回数。" + }, + "word_count": { + "type": "integer", + "description": "チャンクの単語数。" + }, + "segment_position": { + "type": "integer", + "description": "ドキュメント内のチャンクの位置。" + }, + "index_node_hash": { + "type": "string", + "description": "インデックスノードのハッシュ。" + }, + "content": { + "type": "string", + "description": "リソースからのコンテンツスニペット。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "チャンクコンテンツの要約。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ（Unix エポック秒）。" + } + } + }, + "FileUploadResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "一意のファイル ID。" + }, + "name": { + "type": "string", + "description": "ファイル名。" + }, + "size": { + "type": "integer", + "description": "ファイルサイズ（バイト）。" + }, + "extension": { + "type": "string", + "nullable": true, + "description": "ファイル拡張子。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "ファイルの MIME タイプ。" + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ファイルをアップロードしたユーザーの ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "アップロードタイムスタンプ（Unix エポック秒）。" + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "ファイルのプレビュー URL。" + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "ファイルのソース URL。" + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "ファイルの元の URL。" + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられたユーザーの ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられたテナントの ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられた会話の ID。" + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "ファイルのストレージキー。" + } + } + }, + "EndUserDetail": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "エンドユーザー ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "テナント ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "アプリケーション ID。" + }, + "type": { + "type": "string", + "description": "エンドユーザーのタイプ。Service API ユーザーの場合は常に `service_api` です。" + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "API リクエストで提供された `user` 識別子です（例：[完了メッセージを送信](/api-reference/完了メッセージ/完了メッセージを送信) の `user` フィールド）。" + }, + "name": { + "type": "string", + "nullable": true, + "description": "エンドユーザー名。" + }, + "is_anonymous": { + "type": "boolean", + "description": "ユーザーが匿名かどうかを示します。元の API リクエストで `user` 識別子が提供されなかった場合、`true` になります。" + }, + "session_id": { + "type": "string", + "description": "セッション識別子。デフォルトは `external_user_id` の値です。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最終更新タイムスタンプ。" + } + } + }, + "MessageFeedbackRequest": { + "type": "object", + "description": "メッセージフィードバックを送信するためのリクエストボディ。", + "required": [ + "user" + ], + "properties": { + "rating": { + "type": "string", + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "フィードバック評価。以前送信したフィードバックを取り消すには `null` に設定します。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。開発者が定義し、アプリケーション内での一意性を確保する必要があります。" + }, + "content": { + "type": "string", + "description": "追加の詳細を提供する任意のテキストフィードバック。" + } + } + }, + "AppFeedbacksResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "フィードバック項目のリスト。", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } + } + } + }, + "FeedbackItem": { + "type": "object", + "description": "単一のフィードバック項目。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "フィードバック ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "アプリケーション ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会話 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "メッセージ ID。" + }, + "rating": { + "type": "string", + "description": "フィードバック評価。肯定的な場合は `like`、否定的な場合は `dislike`。" + }, + "content": { + "type": "string", + "nullable": true, + "description": "任意のテキストフィードバック。" + }, + "from_source": { + "type": "string", + "description": "フィードバックのソース。API 経由でエンドユーザーが送信したフィードバックの場合は `user`、コンソールから送信されたフィードバックの場合は `admin`。" + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "フィードバックを送信したエンドユーザー ID。`from_source` が `user` の場合に存在します。" + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "フィードバックを送信したアカウント ID。`from_source` が `admin` の場合に存在します。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最終更新タイムスタンプ。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "音声からテキストへの変換のリクエストボディ。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音声ファイルです。対応形式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。上限：`30 MB`。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "音声認識からの出力テキスト。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "テキストから音声への変換のリクエストボディ。`message_id` または `text` のいずれかを指定してください。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "メッセージ ID です。両方が指定された場合、`text` よりも優先されます。" + }, + "text": { + "type": "string", + "description": "変換する音声コンテンツ。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + }, + "voice": { + "type": "string", + "description": "テキスト読み上げに使用する音声。利用可能な音声は、このアプリに設定された TTS プロバイダーによって異なります。デフォルトには[アプリケーションのパラメータ情報を取得](/api-reference/アプリケーション設定/アプリケーションのパラメータ情報を取得) → `text_to_speech.voice` の `voice` 値を使用してください。" + }, + "streaming": { + "type": "boolean", + "description": "ストリーミングレスポンスを有効にするかどうか。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "アプリケーション名。" + }, + "description": { + "type": "string", + "description": "アプリケーションの説明。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "アプリケーションタグ。" + }, + "mode": { + "type": "string", + "description": "アプリケーションモード。`completion` はテキスト生成アプリ、`chat` は基本チャットアプリ、`agent-chat` はエージェントベースのアプリ、`advanced-chat` は Chatflow アプリ、`workflow` はワークフローアプリです。" + }, + "author_name": { + "type": "string", + "description": "アプリケーション作成者の名前。" + } + } + }, + "CompletionAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "開始時に表示されるオープニングステートメント。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "推奨される初期質問のリスト。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答後の推奨質問の設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "音声からテキストへの変換設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "テキストから音声への変換設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + }, + "voice": { + "type": "string", + "description": "TTS の音声識別子。" + }, + "language": { + "type": "string", + "description": "TTS の言語。" + }, + "autoPlay": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "自動再生設定。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "検索リソースの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "アノテーション返信の設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "類似コンテンツの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "センシティブワードフィルタリングの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "user_input_form": { + "type": "array", + "description": "ユーザー入力フォーム要素のリスト。", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "ファイルアップロードの設定。", + "properties": { + "image": { + "type": "object", + "description": "画像アップロードの設定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "画像アップロードが有効かどうか。" + }, + "number_limits": { + "type": "integer", + "description": "最大画像数。" + }, + "detail": { + "type": "string", + "description": "画像の詳細レベル。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ] + }, + "description": "許可された転送方法。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "システムレベルのパラメータと制限。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "最大ファイルサイズ（MB）。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最大画像ファイルサイズ（MB）。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最大音声ファイルサイズ（MB）。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最大動画ファイルサイズ（MB）。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "ワークフローファイルアップロードの最大ファイル数。" + } + } + } + } + }, + "UserInputFormItem": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } + ] + }, + "TextInputControlWrapper": { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } + }, + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } + }, + "SelectControlWrapper": { + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } + }, + "TextInputControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "フォームフィールドの表示ラベル。" + }, + "variable": { + "type": "string", + "description": "`inputs` オブジェクトのキーとして使用される変数名。" + }, + "required": { + "type": "boolean", + "description": "送信前にこのフィールドを入力する必要があるかどうか。" + }, + "default": { + "type": "string", + "description": "フォームフィールドに事前入力されるデフォルト値。" + } + } + }, + "ParagraphControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "フォームフィールドの表示ラベル。" + }, + "variable": { + "type": "string", + "description": "`inputs` オブジェクトのキーとして使用される変数名。" + }, + "required": { + "type": "boolean", + "description": "送信前にこのフィールドを入力する必要があるかどうか。" + }, + "default": { + "type": "string", + "description": "フォームフィールドに事前入力されるデフォルト値。" + } + } + }, + "SelectControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "フォームフィールドの表示ラベル。" + }, + "variable": { + "type": "string", + "description": "`inputs` オブジェクトのキーとして使用される変数名。" + }, + "required": { + "type": "boolean", + "description": "送信前に選択を行う必要があるかどうか。" + }, + "default": { + "type": "string", + "description": "デフォルトで選択される値。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "このフォームコントロールの選択可能な値のリスト。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "アイコンの URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "ツールアイコン。キーはツール名です。" + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "絵文字を使用したツールアイコンの詳細。", + "properties": { + "background": { + "type": "string", + "description": "16進数形式の背景色。" + }, + "content": { + "type": "string", + "description": "Emoji コンテンツ。" + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp タイトル。" + }, + "chat_color_theme": { + "type": "string", + "description": "チャットカラーテーマ。" + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "チャットカラーテーマが反転しているかどうか。" + }, + "icon_type": { + "type": "string", + "description": "使用されるアイコンのタイプ。`emoji` は絵文字アイコン、`image` はアップロードされた画像アイコンです。" + }, + "icon": { + "type": "string", + "description": "アイコンのコンテンツ（絵文字または画像 ID）。" + }, + "icon_background": { + "type": "string", + "description": "アイコンの背景色。" + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "アイコン画像の URL。" + }, + "description": { + "type": "string", + "description": "WebApp の説明。" + }, + "copyright": { + "type": "string", + "description": "著作権テキスト。" + }, + "privacy_policy": { + "type": "string", + "description": "プライバシーポリシー URL。" + }, + "custom_disclaimer": { + "type": "string", + "description": "カスタム免責事項テキスト。" + }, + "default_language": { + "type": "string", + "description": "デフォルト言語コード。" + }, + "show_workflow_steps": { + "type": "boolean", + "description": "ワークフローステップを表示するかどうか。" + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "アプリアイコンを回答アイコンとして使用するかどうか。" + } + } + } } }, "tags": [ - { "name": "完了メッセージ", "description": "テキスト生成と完了に関連する操作。" }, - { "name": "ファイル操作", "description": "ファイル管理に関連する操作。" }, - { "name": "エンドユーザー", "description": "エンドユーザー情報に関連する操作。" }, - { "name": "メッセージフィードバック", "description": "ユーザーフィードバックに関連する操作。" }, - { "name": "音声変換", "description": "テキストから音声への変換に関連する操作。" }, - { "name": "アプリケーション情報", "description": "アプリケーションの設定と情報を取得する操作。" } + { + "name": "完了メッセージ", + "description": "テキスト生成に関連する操作です。" + }, + { + "name": "ファイル操作", + "description": "ファイル管理に関連する操作です。" + }, + { + "name": "エンドユーザー", + "description": "エンドユーザー情報に関連する操作です。" + }, + { + "name": "メッセージフィードバック", + "description": "ユーザーフィードバックに関連する操作です。" + }, + { + "name": "音声・テキスト変換", + "description": "テキスト読み上げと音声認識に関連する操作です。" + }, + { + "name": "アプリケーション設定", + "description": "アプリケーション設定と情報を取得する操作です。" + } ] -} \ No newline at end of file +} diff --git a/ja/api-reference/openapi_knowledge.json b/ja/api-reference/openapi_knowledge.json index d55eecd8..c5f92c08 100644 --- a/ja/api-reference/openapi_knowledge.json +++ b/ja/api-reference/openapi_knowledge.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "ナレッジAPI", - "description": "ナレッジベース（データセット）、ドキュメント、セグメントの管理API。作成、取得、設定が可能です。", + "description": "ナレッジベース、ドキュメント、チャンク、メタデータ、タグの管理（作成、取得、設定を含む）のための API です。**注意：**単一のナレッジベース API キーは、同じアカウント配下のすべての可視ナレッジベースを操作する権限を持ちます。データセキュリティにご注意ください。", "version": "1.0.0" }, "servers": [ { "url": "{apiBaseUrl}", - "description": "ナレッジAPIのベースURL。", + "description": "Knowledge API のベース URL です。", "variables": { "apiBaseUrl": { "default": "https://api.dify.ai/v1", - "description": "APIの実際のベースURL" + "description": "API の実際のベース URL" } } } @@ -25,23 +25,31 @@ "tags": [ { "name": "データセット", - "description": "ナレッジベース（データセット）の管理に関連する操作。" + "description": "ナレッジベースの作成、設定、取得を含むナレッジベース管理の操作です。" }, { "name": "ドキュメント", - "description": "データセット内のドキュメントの作成、更新、管理のための操作。" + "description": "ナレッジベース内のドキュメントの作成、更新、管理のための操作です。" }, { "name": "チャンク", - "description": "ドキュメントのチャンク（セグメント）の管理のための操作。" + "description": "ドキュメントチャンクと子チャンクの管理のための操作です。" }, { - "name": "メタデータ・タグ", - "description": "データセットタグとメタデータの管理のための操作。" + "name": "メタデータ", + "description": "ナレッジベースのメタデータフィールドとドキュメントメタデータ値の管理のための操作です。" + }, + { + "name": "タグ管理", + "description": "ナレッジベースタグとタグバインディングの管理のための操作です。" }, { "name": "モデル", - "description": "利用可能なモデルの取得のための操作。" + "description": "利用可能なモデルを取得するための操作です。" + }, + { + "name": "ナレッジパイプライン", + "description": "データソースプラグインとパイプライン実行を含むナレッジパイプラインの管理と実行のための操作です。" } ], "paths": { @@ -51,31 +59,187 @@ "データセット" ], "summary": "空のナレッジベースを作成", - "description": "指定された設定で新しい空のナレッジベース（データセット）を作成します。", + "description": "新しい空のナレッジベースを作成します。作成後、[テキストからドキュメントを作成](/api-reference/ドキュメント/テキストからドキュメントを作成) または [ファイルからドキュメントを作成](/api-reference/ドキュメント/ファイルからドキュメントを作成) を使用してドキュメントを追加します。", "operationId": "createDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateDatasetRequest" + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "ナレッジベース名。" + }, + "description": { + "type": "string", + "maxLength": 400, + "default": "", + "description": "ナレッジベースの説明です。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` は埋め込みモデルを使用した精密検索、`economy` はキーワードベースのインデキシングです。" + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "default": "only_me", + "description": "このナレッジベースにアクセスできるユーザーを制御します。`only_me` は作成者のみに制限、`all_team_members` はワークスペース全体にアクセスを許可、`partial_members` は指定されたメンバーにアクセスを許可します。" + }, + "provider": { + "type": "string", + "enum": [ + "vendor", + "external" + ], + "default": "vendor", + "description": "`vendor` は内部ナレッジベース、`external` は外部ナレッジベースです。" + }, + "embedding_model": { + "type": "string", + "description": "埋め込みモデル名です。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `model` フィールドの値を使用します。" + }, + "embedding_model_provider": { + "type": "string", + "description": "埋め込みモデルプロバイダーです。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `provider` フィールドの値を使用します。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "外部ナレッジ API 接続の ID です。" + }, + "external_knowledge_id": { + "type": "string", + "description": "外部ナレッジベースの ID です。" + }, + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "サマリーインデックスの設定です。", + "properties": { + "enable": { + "type": "boolean", + "description": "サマリーインデックスを有効にするかどうかです。" + }, + "model_name": { + "type": "string", + "description": "要約生成に使用されるモデルの名前です。" + }, + "model_provider_name": { + "type": "string", + "description": "要約生成モデルのプロバイダーです。" + }, + "summary_prompt": { + "type": "string", + "description": "要約生成用のカスタムプロンプトテンプレートです。" + } + } + } + } } } } }, "responses": { "200": { - "description": "データセットの作成に成功しました。", + "description": "ナレッジベースが正常に作成されました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "プロダクト API 技術ドキュメント", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "description": "`dataset_name_duplicate` : ナレッジベース名は既に存在します。名前を変更してください。", + "content": { + "application/json": { + "examples": { + "dataset_name_duplicate": { + "summary": "dataset_name_duplicate", + "value": { + "status": 409, + "code": "dataset_name_duplicate", + "message": "The dataset name already exists. Please modify your dataset name." + } + } + } + } + } } } }, @@ -84,21 +248,47 @@ "データセット" ], "summary": "ナレッジベースリストを取得", - "description": "ページネーションとフィルタリングのオプション付きでナレッジベースのリストを取得します。", + "description": "ナレッジベースのページネーションリストを返します。キーワードとタグによるフィルタリングをサポートしています。", "operationId": "listDatasets", "parameters": [ + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "description": "取得するページ番号。" + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "1 ページあたりの件数です。" + }, { "name": "keyword", "in": "query", - "description": "名前でデータセットをフィルタするための検索キーワード。", "schema": { "type": "string" - } + }, + "description": "名前でフィルタリングする検索キーワードです。" + }, + { + "name": "include_all", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "権限に関係なくすべてのナレッジベースを含めるかどうかです。" }, { "name": "tag_ids", "in": "query", - "description": "フィルタするタグIDのリスト。データセットは指定されたすべてのタグを持つ必要があります。", "schema": { "type": "array", "items": { @@ -106,45 +296,104 @@ } }, "style": "form", - "explode": false - }, - { - "name": "page", - "in": "query", - "description": "ページネーションのページ番号。", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "1ページあたりに返すアイテム数。", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } - }, - { - "name": "include_all", - "in": "query", - "description": "すべてのデータセットを含めるかどうか。これはワークスペースオーナーにのみ有効です。", - "schema": { - "type": "boolean", - "default": false - } + "explode": true, + "description": "フィルタリングに使用するタグ ID です。" } ], "responses": { "200": { - "description": "データセットのページネーションリスト。", + "description": "ナレッジベースのリストです。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "ナレッジベースオブジェクトの配列です。", + "items": { + "$ref": "#/components/schemas/Dataset" + } + }, + "has_more": { + "type": "boolean", + "description": "次のページにさらに項目が存在するかどうかです。" + }, + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "一致する項目の合計数です。" + }, + "page": { + "type": "integer", + "description": "現在のページ番号です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "プロダクト API 技術ドキュメント", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } } } } @@ -158,27 +407,115 @@ "データセット" ], "summary": "ナレッジベース詳細を取得", - "description": "IDで特定のナレッジベースの詳細情報を取得します。", + "description": "特定のナレッジベースの詳細情報（埋め込みモデル、検索設定、ドキュメント統計を含む）を取得します。", "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースの一意識別子。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" } ], "responses": { "200": { - "description": "データセットに関する詳細情報。", + "description": "ナレッジベースの詳細です。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "プロダクト API 技術ドキュメント", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このナレッジベースにアクセスする権限がありません。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } } } } @@ -190,18 +527,18 @@ "データセット" ], "summary": "ナレッジベースを更新", - "description": "特定のナレッジベースの設定を更新します。", + "description": "既存のナレッジベースの名前、説明、権限、または検索設定を更新します。リクエストボディで指定されたフィールドのみが更新されます。", "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースの一意識別子。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" } ], "requestBody": { @@ -209,24 +546,191 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateDatasetRequest" + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "ナレッジベース名。" + }, + "description": { + "type": "string", + "maxLength": 400, + "description": "ナレッジベースの説明です。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` は埋め込みモデルを使用した精密検索、`economy` はキーワードベースのインデキシングです。" + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "description": "このナレッジベースにアクセスできるユーザーを制御します。`only_me` は作成者のみに制限、`all_team_members` はワークスペース全体にアクセスを許可、`partial_members` は指定されたメンバーにアクセスを許可します。" + }, + "embedding_model": { + "type": "string", + "description": "埋め込みモデル名です。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `model` フィールドの値を使用します。" + }, + "embedding_model_provider": { + "type": "string", + "description": "埋め込みモデルプロバイダーです。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `provider` フィールドの値を使用します。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。" + }, + "partial_member_list": { + "type": "array", + "description": "`permission` が `partial_members` の場合にアクセス権を持つチームメンバーのリストです。", + "items": { + "type": "object", + "properties": { + "user_id": { + "type": "string", + "description": "アクセス権を付与するチームメンバーの ID です。" + } + } + } + }, + "external_retrieval_model": { + "type": "object", + "description": "外部ナレッジベースの検索設定です。", + "properties": { + "top_k": { + "type": "integer", + "description": "返す結果の最大数です。" + }, + "score_threshold": { + "type": "number", + "description": "結果フィルタリング用の最小関連性スコア閾値です。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "スコア閾値フィルタリングが有効かどうかです。" + } + } + }, + "external_knowledge_id": { + "type": "string", + "description": "外部ナレッジベースの ID です。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "外部ナレッジ API 接続の ID です。" + } + } } } } }, "responses": { "200": { - "description": "データセット詳細の更新に成功しました。", + "description": "ナレッジベースが正常に更新されました。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "プロダクト API 技術ドキュメント", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, - "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "403": { + "description": "`forbidden` : このナレッジベースにアクセスする権限がありません。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } }, @@ -235,23 +739,57 @@ "データセット" ], "summary": "ナレッジベースを削除", - "description": "ナレッジベースとそれに関連するすべてのドキュメントとデータを削除します。", + "description": "ナレッジベースとそのすべてのドキュメントを完全に削除します。対象のナレッジベースはどのアプリケーションでも使用されていない必要があります。", "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "削除するナレッジベースの一意識別子。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" } ], "responses": { "204": { - "description": "データセットの削除に成功しました。" + "description": "Success." + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "409": { + "description": "`dataset_in_use` : このナレッジベースは一部のアプリで使用されています。削除する前にアプリから削除してください。", + "content": { + "application/json": { + "examples": { + "dataset_in_use": { + "summary": "dataset_in_use", + "value": { + "status": 409, + "code": "dataset_in_use", + "message": "The dataset is being used by some apps. Please remove the dataset from the apps before deleting it." + } + } + } + } + } } } } @@ -262,18 +800,18 @@ "ドキュメント" ], "summary": "テキストからドキュメントを作成", - "description": "テキストコンテンツから既存のナレッジベース内に新しいドキュメントを直接作成します。", + "description": "テキストコンテンツからドキュメントを作成します。ドキュメントは非同期で処理されます——返された `batch` ID を [ドキュメント埋め込みステータス（進捗）を取得](/api-reference/ドキュメント/ドキュメント埋め込みステータス（進捗）を取得) で使用して進捗を追跡します。", "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ドキュメントを追加するナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" } ], "requestBody": { @@ -281,18 +819,222 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateDocumentByTextRequest" + "type": "object", + "required": [ + "name", + "text" + ], + "properties": { + "name": { + "type": "string", + "description": "ドキュメント名です。" + }, + "text": { + "type": "string", + "description": "ドキュメントのテキスト内容です。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "description": "ナレッジベースに最初のドキュメントを追加する際に必須です。以降のドキュメントでは省略するとナレッジベースのインデックス方式を継承します。`high_quality` は埋め込みモデルによる精密検索、`economy` はキーワードベースのインデックスを使用します。" + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` は標準テキストチャンキング、`hierarchical_model` は親子チャンク構造、`qa_model` は質問・回答ペアの抽出です。" + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "処理最適化のためのドキュメント言語です。" + }, + "process_rule": { + "type": "object", + "description": "チャンキングの処理ルールです。", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "処理モードです。`automatic` は組み込みルールを使用、`custom` は手動設定が可能、`hierarchical` は親子チャンク構造を有効にします（`doc_form: hierarchical_model` と組み合わせて使用）。" + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "ルール識別子です。" + }, + "enabled": { + "type": "boolean", + "description": "この前処理ルールが有効かどうかです。" + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "テキスト分割用のカスタムセパレーターです。" + }, + "max_tokens": { + "type": "integer", + "description": "チャンクあたりの最大トークン数です。" + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "チャンク間のトークンオーバーラップです。" + } + } + } + } + } + } + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。" + }, + "embedding_model": { + "type": "string", + "description": "埋め込みモデル名です。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `model` フィールドの値を使用します。" + }, + "embedding_model_provider": { + "type": "string", + "description": "埋め込みモデルプロバイダーです。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `provider` フィールドの値を使用します。" + }, + "original_document_id": { + "type": "string", + "description": "バージョン管理用の元ドキュメント ID です。" + } + } } } } }, "responses": { "200": { - "description": "ドキュメントが正常に作成され、インデックス化されています。", + "description": "ドキュメントが正常に作成されました。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "インデックス進捗を追跡するためのバッチ ID です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。設定 → モデルプロバイダーで認証情報を完了してください。\n- `invalid_param` : ナレッジベースが存在しません。/ indexing_technique は必須です。", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + } } } } @@ -306,18 +1048,18 @@ "ドキュメント" ], "summary": "ファイルからドキュメントを作成", - "description": "ファイルをアップロードして既存のナレッジベース内に新しいドキュメントを作成します。", + "description": "ファイルをアップロードしてドキュメントを作成します。一般的なドキュメント形式（PDF、TXT、DOCX など）をサポートしています。処理は非同期で行われます——返された `batch` ID を [ドキュメント埋め込みステータス（進捗）を取得](/api-reference/ドキュメント/ドキュメント埋め込みステータス（進捗）を取得) で使用して進捗を追跡します。", "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ドキュメントを追加するナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" } ], "requestBody": { @@ -326,16 +1068,19 @@ "multipart/form-data": { "schema": { "type": "object", + "required": [ + "file" + ], "properties": { - "data": { - "type": "string", - "description": "ドキュメントメタデータと処理ルールを含むJSON文字列。詳細は`CreateDocumentByFileRequestData`スキーマを参照してください。", - "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\":{\"separator\":\"###\", \"max_tokens\":500}}},\"summary_index_setting\":{\"enable\":true,\"model_name\":\"qwen-vl-plus\",\"model_provider_name\":\"langgenius/tongyi/tongyi\",\"summary_prompt\":\"summarize the text\"}}" - }, "file": { "type": "string", "format": "binary", - "description": "アップロードするファイル。" + "description": "アップロードするファイルです。" + }, + "data": { + "type": "string", + "description": "設定情報を含む JSON 文字列です。[テキストからドキュメントを作成](/api-reference/ドキュメント/テキストからドキュメントを作成) と同じフィールド（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`）を受け付けますが、`name` と `text` は除きます。", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } @@ -344,179 +1089,228 @@ }, "responses": { "200": { - "description": "ドキュメントが正常に作成され、インデックス化されています。", + "description": "ドキュメントが正常に作成されました。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "インデックス進捗を追跡するためのバッチ ID です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } } } } }, "400": { - "$ref": "#/components/responses/FileError" - }, - "413": { - "$ref": "#/components/responses/FileTooLarge" - }, - "415": { - "$ref": "#/components/responses/UnsupportedFileType" - } - } - } - }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { - "post": { - "tags": [ - "ドキュメント" - ], - "summary": "テキストでドキュメントを更新", - "description": "テキストを使用して既存のドキュメントのコンテンツまたは設定を更新します。", - "operationId": "updateDocumentByText", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "ドキュメントを含むナレッジベースのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "更新するドキュメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateDocumentByTextRequest" - } - } - } - }, - "responses": { - "200": { - "description": "ドキュメントが正常に更新されました。", + "description": "- `no_file_uploaded` : ファイルをアップロードしてください。\n- `too_many_files` : ファイルは 1 つのみ許可されています。\n- `filename_not_exists_error` : 指定されたファイル名が存在しません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。設定 → モデルプロバイダーで認証情報を完了してください。\n- `invalid_param` : ナレッジベースが存在しない、外部データセットは非対応、ファイルが大きすぎる、サポートされていないファイルタイプ、または必須フィールドが不足しています。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" - } - } - } - } - } - } - }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { - "post": { - "tags": [ - "ドキュメント" - ], - "summary": "ファイルでドキュメントを更新", - "description": "新しいファイルをアップロードして既存のドキュメントを更新し、そのコンテンツを置き換えます。", - "operationId": "updateDocumentByFile", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "ドキュメントを含むナレッジベースのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "更新するドキュメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "string", - "description": "オプションのドキュメント名と処理ルールを含むJSON文字列。`UpdateDocumentByFileRequestData`スキーマを参照してください。", - "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } }, - "file": { - "type": "string", - "format": "binary", - "description": "アップロードする新しいファイル。" + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param (indexing_technique)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + }, + "invalid_param_process_rule": { + "summary": "invalid_param (process_rule)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "process_rule is required." + } } } } } } - }, - "responses": { - "200": { - "description": "ドキュメントが正常に更新されました。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" - } - } - } - } } } }, - "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "/datasets/{dataset_id}/documents": { "get": { "tags": [ "ドキュメント" ], - "summary": "ドキュメント埋め込みステータス（進捗）を取得", - "description": "ドキュメントのバッチのインデックス化ステータスを取得し、埋め込みと処理の進捗を表示します。", - "operationId": "getDocumentIndexingStatus", + "summary": "ナレッジベースのドキュメントリストを取得", + "description": "ナレッジベース内のドキュメントのページネーションされた一覧を返します。キーワードやインデックスステータスによるフィルタリングをサポートしています。", + "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { - "name": "batch", - "in": "path", - "required": true, - "description": "ドキュメント作成エンドポイントから返されるバッチ番号。", + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "description": "取得するページ番号。" + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "1 ページあたりの項目数です。サーバーの上限は `100` です。" + }, + { + "name": "keyword", + "in": "query", "schema": { "type": "string" - } + }, + "description": "ドキュメント名でフィルタリングするための検索キーワードです。" + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "queuing", + "indexing", + "paused", + "error", + "available", + "disabled", + "archived" + ] + }, + "description": "表示ステータスでフィルタリングします。" } ], "responses": { "200": { - "description": "バッチ内のドキュメントのインデックス化ステータス。", + "description": "ドキュメントのリストです。", "content": { "application/json": { "schema": { @@ -524,9 +1318,94 @@ "properties": { "data": { "type": "array", + "description": "ナレッジベースオブジェクトの配列です。", "items": { - "$ref": "#/components/schemas/IndexingStatus" + "$ref": "#/components/schemas/Document" } + }, + "has_more": { + "type": "boolean", + "description": "次のページにさらに項目が存在するかどうかです。" + }, + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "一致する項目の合計数です。" + }, + "page": { + "type": "integer", + "description": "現在のページ番号です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." } } } @@ -542,33 +1421,32 @@ "ドキュメント" ], "summary": "ドキュメント詳細を取得", - "description": "処理ルールとステータスを含む単一ドキュメントの詳細情報を取得します。", + "description": "特定のドキュメントの詳細情報（インデックスステータス、メタデータ、処理統計を含む）を取得します。", "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "metadata", "in": "query", - "description": "メタデータフィルタ：`all`はすべてのメタデータを返し、`only`はカスタムメタデータのみを返し、`without`はメタデータを返しません。", "schema": { "type": "string", "enum": [ @@ -577,16 +1455,281 @@ "without" ], "default": "all" - } + }, + "description": "`all` はメタデータを含むすべてのフィールドを返します。`only` は `id`、`doc_type`、`doc_metadata` のみを返します。`without` は `doc_metadata` を除くすべてのフィールドを返します。" } ], "responses": { "200": { - "description": "ドキュメントに関する詳細情報。", + "description": "ドキュメントの詳細です。レスポンスの形式は `metadata` クエリパラメータによって異なります。`metadata` が `only` の場合、`id`、`doc_type`、`doc_metadata` のみが返されます。`metadata` が `without` の場合、`doc_type` と `doc_metadata` は省略されます。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentDetail" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ドキュメント識別子です。" + }, + "position": { + "type": "integer", + "description": "ナレッジベース内の位置インデックスです。" + }, + "data_source_type": { + "type": "string", + "description": "ドキュメントのアップロード方法です。ファイルアップロードの場合は `upload_file`、Notion インポートの場合は `notion_import` です。" + }, + "data_source_info": { + "type": "object", + "description": "生データソース情報です。" + }, + "dataset_process_rule_id": { + "type": "string", + "description": "このドキュメントに適用された処理ルールの ID です。" + }, + "dataset_process_rule": { + "type": "object", + "description": "ナレッジベースレベルの処理ルール設定です。" + }, + "document_process_rule": { + "type": "object", + "description": "ドキュメントレベルの処理ルール設定です。" + }, + "name": { + "type": "string", + "description": "ドキュメント名です。" + }, + "created_from": { + "type": "string", + "description": "ドキュメントの作成元です。API で作成した場合は `api`、UI で作成した場合は `web` です。" + }, + "created_by": { + "type": "string", + "description": "ドキュメントを作成したユーザーの ID です。" + }, + "created_at": { + "type": "number", + "description": "ドキュメント作成の Unix タイムスタンプです。" + }, + "tokens": { + "type": "integer", + "description": "ドキュメント内のトークン数です。" + }, + "indexing_status": { + "type": "string", + "description": "現在のインデックスステータスです（例：`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、`error`、`paused`）。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "インデックス作成が失敗した場合のエラーメッセージです。それ以外は `null` です。" + }, + "enabled": { + "type": "boolean", + "description": "このドキュメントが検索に対して有効かどうかです。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "ドキュメントが無効化された Unix タイムスタンプです。有効な場合は `null` です。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "ドキュメントを無効化したユーザーの ID です。有効な場合は `null` です。" + }, + "archived": { + "type": "boolean", + "description": "ドキュメントがアーカイブ済みかどうかです。" + }, + "display_status": { + "type": "string", + "description": "UI 向けの表示用インデックスステータスです。" + }, + "word_count": { + "type": "integer", + "description": "ドキュメントの合計単語数です。" + }, + "hit_count": { + "type": "integer", + "description": "このドキュメントが検索された回数です。" + }, + "doc_form": { + "type": "string", + "description": "ドキュメントのチャンキングモードです。`text_model` は標準テキスト、`hierarchical_model` は親子構造、`qa_model` は QA ペアを示します。" + }, + "doc_language": { + "type": "string", + "description": "ドキュメント内容の言語です。" + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "ドキュメントタイプの分類です。未設定の場合は `null` です。" + }, + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデータフィールドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデータフィールド名です。" + }, + "type": { + "type": "string", + "description": "メタデータフィールドの種類です。" + }, + "value": { + "type": "string", + "description": "このドキュメントのメタデータフィールド値。" + } + } + }, + "description": "このドキュメントのカスタムメタデータキーバリューペア。" + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "処理が完了した Unix タイムスタンプです。まだ完了していない場合は `null` です。" + }, + "updated_at": { + "type": "number", + "nullable": true, + "description": "最終更新の Unix タイムスタンプです。更新されたことがない場合は `null` です。" + }, + "indexing_latency": { + "type": "number", + "nullable": true, + "description": "インデックス作成にかかった時間（秒）です。未完了の場合は `null` です。" + }, + "segment_count": { + "type": "integer", + "description": "ドキュメント内のチャンク数です。" + }, + "average_segment_length": { + "type": "number", + "description": "チャンクの平均文字長です。" + }, + "summary_index_status": { + "type": "string", + "nullable": true, + "description": "要約インデックスのステータスです。要約インデックスが有効でない場合は `null` です。" + }, + "need_summary": { + "type": "boolean", + "description": "このドキュメントが要約生成を必要とするかどうかです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "dataset_process_rule": { + "id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "mode": "custom" + }, + "document_process_rule": { + "mode": "custom", + "rules": { + "pre_processing_rules": [], + "segmentation": { + "separator": "###", + "max_tokens": 500, + "chunk_overlap": 50 + } + } + }, + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_language": "English", + "doc_type": null, + "doc_metadata": [], + "completed_at": 1741267260, + "updated_at": 1741267260, + "indexing_latency": 60.0, + "segment_count": 5, + "average_segment_length": 70.0, + "summary_index_status": null, + "need_summary": false + } + } + } + } + } + }, + "400": { + "description": "`invalid_metadata` : 指定されたキーのメタデータ値が無効です。", + "content": { + "application/json": { + "examples": { + "invalid_metadata": { + "summary": "invalid_metadata", + "value": { + "status": 400, + "code": "invalid_metadata", + "message": "Invalid metadata value: {metadata_key}" + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 権限がありません。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ドキュメントが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } @@ -598,92 +1741,81 @@ "ドキュメント" ], "summary": "ドキュメントを削除", - "description": "ナレッジベースから特定のドキュメントを削除します。", + "description": "ナレッジベースからドキュメントとそのすべてのチャンクを完全に削除します。", "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "削除するドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "responses": { "204": { - "description": "ドキュメントの削除に成功しました。" - } - } - } - }, - "/datasets/{dataset_id}/documents": { - "get": { - "tags": [ - "ドキュメント" - ], - "summary": "ナレッジベースのドキュメントリストを取得", - "description": "指定されたナレッジベース内のすべてのドキュメントのページネーションリストを取得します。", - "operationId": "listDocuments", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "ナレッジベースのID。", - "schema": { - "type": "string", - "format": "uuid" - } + "description": "Success." }, - { - "name": "keyword", - "in": "query", - "description": "ドキュメント名で検索するキーワード。", - "schema": { - "type": "string" - } - }, - { - "name": "page", - "in": "query", - "description": "ページネーションのページ番号。", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "1ページあたりに返すアイテム数。", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } - } - ], - "responses": { - "200": { - "description": "ドキュメントのページネーションリスト。", + "400": { + "description": "`document_indexing` : インデキシング中はドキュメントを削除できません。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentListResponse" + "examples": { + "document_indexing": { + "summary": "document_indexing", + "value": { + "status": 400, + "code": "document_indexing", + "message": "Cannot delete document during indexing." + } + } + } + } + } + }, + "403": { + "description": "`archived_document_immutable` : アーカイブされたドキュメントは編集できません。", + "content": { + "application/json": { + "examples": { + "archived_document_immutable": { + "summary": "archived_document_immutable", + "value": { + "status": 403, + "code": "archived_document_immutable", + "message": "The archived document is not editable." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ドキュメントが存在しません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document Not Exists." + } + } } } } @@ -691,39 +1823,689 @@ } } }, - "/datasets/{dataset_id}/documents/status/{action}": { - "patch": { + "/datasets/{dataset_id}/documents/{document_id}/download": { + "get": { "tags": [ "ドキュメント" ], - "summary": "ドキュメントステータスを更新", - "description": "1つまたは複数のドキュメントのステータスを更新するバッチアクションを実行します（例：有効化、無効化、アーカイブ）。", - "operationId": "batchUpdateDocumentStatus", + "summary": "ドキュメントをダウンロード", + "description": "ドキュメントの元のアップロードファイルの署名付きダウンロード URL を取得します。", + "operationId": "downloadDocumentJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { - "name": "action", + "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントに対して実行するアクション。", "schema": { "type": "string", - "enum": [ - "enable", - "disable", - "archive", - "un_archive" - ] + "format": "uuid" + }, + "description": "Document ID." + } + ], + "responses": { + "200": { + "description": "ダウンロード URL が正常に生成されました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "元のアップロードファイルをダウンロードするための署名付き URL です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600" + } + } + } + } } + }, + "403": { + "description": "`forbidden` : このドキュメントにアクセスする権限がありません。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ドキュメントが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "get": { + "tags": [ + "ドキュメント" + ], + "summary": "ドキュメント埋め込みステータス（進捗）を取得", + "description": "バッチ内のドキュメントのインデックス進捗を確認します。各ドキュメントの現在の処理段階とチャンク完了数を返します。`indexing_status` が `completed` または `error` に達するまでこのエンドポイントをポーリングしてください。ステータスは次の順序で進行します：`waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`。", + "operationId": "getDocumentIndexingStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + }, + { + "name": "batch", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "ドキュメント作成時に返されるバッチ ID です。" + } + ], + "responses": { + "200": { + "description": "バッチ内のドキュメントのインデックス状態です。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ドキュメント識別子です。" + }, + "indexing_status": { + "type": "string", + "description": "現在のインデックスステータスです：`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、または `error`。" + }, + "processing_started_at": { + "type": "number", + "description": "処理開始時の Unix タイムスタンプです。" + }, + "parsing_completed_at": { + "type": "number", + "description": "パース完了時の Unix タイムスタンプです。" + }, + "cleaning_completed_at": { + "type": "number", + "description": "クリーニング完了時の Unix タイムスタンプです。" + }, + "splitting_completed_at": { + "type": "number", + "description": "分割完了時の Unix タイムスタンプです。" + }, + "completed_at": { + "type": "number", + "description": "インデックス完了時の Unix タイムスタンプです。" + }, + "paused_at": { + "type": "number", + "nullable": true, + "description": "インデキシングが一時停止されたタイムスタンプ。一時停止されていない場合は `null`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "インデキシングが失敗した場合のエラーメッセージ。エラーがない場合は `null`。" + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "インデキシングが停止されたタイムスタンプ。停止されていない場合は `null`。" + }, + "completed_segments": { + "type": "integer", + "description": "インデックス済みのチャンク数です。" + }, + "total_segments": { + "type": "integer", + "description": "インデックス対象のチャンクの合計数です。" + } + } + }, + "description": "インデキシングステータスエントリのリスト。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "indexing_status": "completed", + "processing_started_at": 1741267200, + "parsing_completed_at": 1741267200, + "cleaning_completed_at": 1741267200, + "splitting_completed_at": 1741267200, + "completed_at": 1741267200, + "paused_at": null, + "error": null, + "stopped_at": null, + "completed_segments": 5, + "total_segments": 5 + } + ] + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。/ ドキュメントが見つかりません。", + "content": { + "application/json": { + "examples": { + "dataset_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + }, + "documents_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Documents not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { + "post": { + "tags": [ + "ドキュメント" + ], + "summary": "テキストでドキュメントを更新", + "description": "既存ドキュメントのテキストコンテンツ、名前、または処理設定を更新します。コンテンツが変更された場合はインデックスが再トリガーされます——返された `batch` ID を [ドキュメント埋め込みステータス（進捗）を取得](/api-reference/ドキュメント/ドキュメント埋め込みステータス（進捗）を取得) で使用して進捗を追跡します。", + "operationId": "updateDocumentByText", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "ドキュメント名です。`text` を指定する場合は必須です。" + }, + "text": { + "type": "string", + "description": "ドキュメントのテキスト内容です。" + }, + "process_rule": { + "type": "object", + "description": "チャンキングの処理ルールです。", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "処理モードです。`automatic` は組み込みルールを使用、`custom` は手動設定が可能、`hierarchical` は親子チャンク構造を有効にします（`doc_form: hierarchical_model` と組み合わせて使用）。" + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "ルール識別子です。" + }, + "enabled": { + "type": "boolean", + "description": "この前処理ルールが有効かどうかです。" + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "テキスト分割用のカスタムセパレーターです。" + }, + "max_tokens": { + "type": "integer", + "description": "チャンクあたりの最大トークン数です。" + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "チャンク間のトークンオーバーラップです。" + } + } + } + } + } + } + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` は標準テキストチャンキング、`hierarchical_model` は親子チャンク構造、`qa_model` は質問・回答ペアの抽出です。" + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "処理最適化のためのドキュメント言語です。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "ドキュメントが正常に更新されました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "インデックス進捗を追跡するためのバッチ ID です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。設定 → モデルプロバイダーで認証情報を完了してください。\n- `invalid_param` : ナレッジベースが存在しない、またはテキスト指定時は name が必須です。", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_name_required": { + "summary": "invalid_param (name required)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "name is required when text is provided." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { + "post": { + "tags": [ + "ドキュメント" + ], + "summary": "ファイルでドキュメントを更新", + "description": "新しいファイルをアップロードして既存のドキュメントを更新します。インデックスが再トリガーされます——返された `batch` ID を [ドキュメント埋め込みステータス（進捗）を取得](/api-reference/ドキュメント/ドキュメント埋め込みステータス（進捗）を取得) で使用して進捗を追跡します。", + "operationId": "updateDocumentByFile", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "アップロードするファイルです。" + }, + "data": { + "type": "string", + "description": "設定情報を含む JSON 文字列です。[テキストからドキュメントを作成](/api-reference/ドキュメント/テキストからドキュメントを作成) と同じフィールド（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`）を受け付けますが、`name` と `text` は除きます。", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "ドキュメントが正常に更新されました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "インデックス進捗を追跡するためのバッチ ID です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `too_many_files` : ファイルは 1 つのみ許可されています。\n- `filename_not_exists_error` : 指定されたファイル名が存在しません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。設定 → モデルプロバイダーで認証情報を完了してください。\n- `invalid_param` : ナレッジベースが存在しない、外部データセットは非対応、ファイルが大きすぎる、またはサポートされていないファイルタイプです。", + "content": { + "application/json": { + "examples": { + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/download-zip": { + "post": { + "tags": [ + "ドキュメント" + ], + "summary": "ドキュメントを一括ダウンロード（ZIP）", + "description": "複数のアップロードファイルドキュメントを単一の ZIP アーカイブとしてダウンロードします。最大 `100` 件のドキュメント ID を受け付けます。", + "operationId": "downloadDocumentsZipJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" } ], "requestBody": { @@ -738,11 +2520,13 @@ "properties": { "document_ids": { "type": "array", - "description": "アクションを実行するドキュメントIDのリスト。", + "minItems": 1, + "maxItems": 100, "items": { "type": "string", "format": "uuid" - } + }, + "description": "ZIP アーカイブに含めるドキュメント ID の配列です。" } } } @@ -751,7 +2535,186 @@ }, "responses": { "200": { - "$ref": "#/components/responses/Success" + "description": "リクエストされたドキュメントを含む ZIP アーカイブです。", + "content": { + "application/zip": { + "schema": { + "type": "string", + "format": "binary", + "description": "ZIP アーカイブのバイナリストリームです。" + } + } + } + }, + "403": { + "description": "`forbidden` : 権限が不足しています。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ドキュメントまたはナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/status/{action}": { + "patch": { + "tags": [ + "ドキュメント" + ], + "summary": "ドキュメントステータスを一括更新", + "description": "複数のドキュメントを一括で有効化、無効化、アーカイブ、またはアーカイブ解除します。", + "operationId": "batchUpdateDocumentStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + }, + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable", + "archive", + "un_archive" + ] + }, + "description": "`enable` で有効化、`disable` で無効化、`archive` でアーカイブ、`un_archive` でアーカイブから復元します。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "更新するドキュメント ID のリストです。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "ドキュメントが正常に更新されました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操作結果です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "result": "success" + } + } + } + } + } + }, + "400": { + "description": "`invalid_action` : 無効なアクションです。", + "content": { + "application/json": { + "examples": { + "invalid_action": { + "summary": "invalid_action", + "value": { + "status": 400, + "code": "invalid_action", + "message": "Invalid action." + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 権限が不足しています。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } } @@ -762,28 +2725,28 @@ "チャンク" ], "summary": "ドキュメントにチャンクを追加", - "description": "特定のドキュメントに1つまたは複数の新しいチャンク（セグメント）を追加します。手動でキュレートされたコンテンツを追加するのに便利です。", + "description": "ドキュメント内に 1 つ以上のチャンクを作成します。各チャンクにはオプションのキーワードと回答フィールド（QA モードドキュメント用）を含めることができます。", "operationId": "createSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "requestBody": { @@ -791,18 +2754,135 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateSegmentsRequest" + "type": "object", + "required": [ + "segments" + ], + "properties": { + "segments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "チャンクのテキスト内容です。" + }, + "answer": { + "type": "string", + "description": "QA モードの回答内容です。" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "チャンクのキーワードです。" + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "添付ファイル ID です。" + } + } + }, + "description": "作成するチャンクオブジェクトの配列です。" + } + } } } } }, "responses": { "200": { - "description": "新しく作成されたセグメントのリスト。", + "description": "チャンクが正常に作成されました。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + }, + "description": "作成されたチャンクのリスト。" + }, + "doc_form": { + "type": "string", + "description": "このドキュメントが使用するドキュメントチャンキングモードです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model" + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ドキュメントが完了していないか、無効になっています。", + "content": { + "application/json": { + "examples": { + "not_found_not_completed": { + "summary": "not_found (not completed)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is not completed." + } + }, + "not_found_disabled": { + "summary": "not_found (disabled)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is disabled." + } + } } } } @@ -813,75 +2893,153 @@ "tags": [ "チャンク" ], - "summary": "ドキュメントからチャンクを取得", - "description": "特定のドキュメントからチャンク（セグメント）のページネーションリストを取得します。", + "summary": "チャンク一覧を取得", + "description": "ドキュメント内のチャンクのページネーションリストを返します。キーワードとステータスによるフィルタリングをサポートしています。", "operationId": "listSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } - }, - { - "name": "keyword", - "in": "query", - "description": "コンテンツでセグメントをフィルタするキーワード。", - "schema": { - "type": "string" - } - }, - { - "name": "status", - "in": "query", - "description": "インデックス化ステータスでセグメントをフィルタ。", - "schema": { - "type": "string", - "example": "completed" - } + }, + "description": "Document ID." }, { "name": "page", "in": "query", - "description": "ページネーションのページ番号。", "schema": { "type": "integer", "default": 1 - } + }, + "description": "取得するページ番号。" }, { "name": "limit", "in": "query", - "description": "1ページあたりに返すアイテム数。", "schema": { "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } + "default": 20 + }, + "description": "1 ページあたりの項目数です。サーバーの上限は `100` です。" + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "インデックスステータスでチャンクをフィルタリングします（例：`completed`、`indexing`、`error`）。" + }, + { + "name": "keyword", + "in": "query", + "schema": { + "type": "string" + }, + "description": "検索キーワードです。" } ], "responses": { "200": { - "description": "セグメントのページネーションリスト。", + "description": "チャンクのリストです。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentPaginatedResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + }, + "description": "チャンクのリスト。" + }, + "doc_form": { + "type": "string", + "description": "このドキュメントが使用するドキュメントチャンキングモードです。" + }, + "total": { + "type": "integer", + "description": "一致するチャンクの合計数です。" + }, + "has_more": { + "type": "boolean", + "description": "次のページにさらに項目が存在するかどうかです。" + }, + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "page": { + "type": "integer", + "description": "現在のページ番号です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model", + "total": 1, + "has_more": false, + "limit": 20, + "page": 1 + } + } } } } @@ -895,47 +3053,97 @@ "チャンク" ], "summary": "ドキュメント内のチャンク詳細を取得", - "description": "ドキュメント内の特定のチャンク（セグメント）の詳細を取得します。", + "description": "特定のチャンクの詳細情報（内容、キーワード、インデックスステータスを含む）を取得します。", "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "セグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "responses": { "200": { - "description": "セグメントに関する詳細情報。", + "description": "チャンクの詳細です。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "このドキュメントが使用するドキュメントチャンキングモードです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } @@ -947,38 +3155,38 @@ "チャンク" ], "summary": "ドキュメント内のチャンクを更新", - "description": "特定のチャンク（セグメント）のコンテンツ、キーワード、またはステータスを更新します。", + "description": "チャンクのコンテンツ、キーワード、または回答を更新します。変更されたチャンクのインデックス作成が再トリガーされます。", "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "更新するセグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "requestBody": { @@ -986,18 +3194,115 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateSegmentRequest" + "type": "object", + "required": [ + "segment" + ], + "properties": { + "segment": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "チャンクのテキスト内容です。" + }, + "answer": { + "type": "string", + "description": "QA モードの回答内容です。" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "チャンクのキーワードです。" + }, + "enabled": { + "type": "boolean", + "description": "チャンクが有効かどうかです。" + }, + "regenerate_child_chunks": { + "type": "boolean", + "default": false, + "description": "子チャンクを再生成するかどうかです。" + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "添付ファイル ID です。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "サマリーインデックスのサマリー内容です。" + } + }, + "description": "更新するチャンクデータです。" + } + } } } } }, "responses": { "200": { - "description": "更新されたセグメント詳細。", + "description": "チャンクが正常に更新されました。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "このドキュメントが使用するドキュメントチャンキングモードです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } @@ -1009,117 +3314,43 @@ "チャンク" ], "summary": "ドキュメント内のチャンクを削除", - "description": "ドキュメントから特定のチャンク（セグメント）を削除します。", + "description": "ドキュメントからチャンクを完全に削除します。", "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "削除するセグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "responses": { "204": { - "description": "セグメントの削除に成功しました。" - } - } - } - }, - "/datasets/{dataset_id}/retrieve": { - "post": { - "tags": [ - "データセット" - ], - "summary": "ナレッジベースからチャンクを取得 / テスト検索", - "description": "ナレッジベースに対して検索クエリを実行し、最も関連性の高いチャンク（セグメント）を取得します。このエンドポイントは、本番環境での検索とテスト検索の両方に使用できます。", - "operationId": "retrieveSegments", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "取得元のナレッジベースのID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RetrieveRequest" - } - } - } - }, - "responses": { - "200": { - "description": "クエリにマッチする取得されたセグメントのリスト。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RetrieveResponse" - } - } - } - } - } - } - }, - "/workspaces/current/models/model-types/text-embedding": { - "get": { - "tags": [ - "モデル" - ], - "summary": "利用可能な埋め込みモデルを取得", - "description": "ナレッジベースの作成とクエリに使用できるすべての利用可能なテキスト埋め込みモデルのリストを取得します。", - "operationId": "getAvailableEmbeddingModels", - "responses": { - "200": { - "description": "プロバイダー別にグループ化された利用可能な埋め込みモデルのリスト。", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ModelProvider" - } - } - } - } - } - } + "description": "Success." } } } @@ -1130,38 +3361,38 @@ "チャンク" ], "summary": "子チャンクを作成", - "description": "階層モードを使用してドキュメント内の親セグメントの下に新しい子チャンクを作成します。", + "description": "親チャンクの下に子チャンクを作成します。`hierarchical_model` チャンキングモードを使用しているドキュメントでのみ利用可能です。", "operationId": "createChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "親セグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "requestBody": { @@ -1169,18 +3400,66 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateChildChunkRequest" + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "子チャンクのテキスト内容です。" + } + } } } } }, "responses": { "200": { - "description": "子チャンクの作成に成功しました。", + "description": "子チャンクが正常に作成されました。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 子チャンクインデックスの作成に失敗しました。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } + } } } } @@ -1191,75 +3470,124 @@ "tags": [ "チャンク" ], - "summary": "子チャンクを取得", - "description": "特定の親セグメントの子チャンクのリストを取得します。", + "summary": "子チャンク一覧を取得", + "description": "特定の親チャンク配下の子チャンクのページネーションリストを返します。", "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "親セグメントのID。", "schema": { "type": "string", "format": "uuid" - } - }, - { - "name": "keyword", - "in": "query", - "description": "子チャンクをフィルタする検索キーワード。", - "schema": { - "type": "string" - } + }, + "description": "Chunk ID." }, { "name": "page", "in": "query", - "description": "ページネーションのページ番号。", "schema": { "type": "integer", - "default": 1 - } + "default": 1, + "minimum": 1 + }, + "description": "取得するページ番号。" }, { "name": "limit", "in": "query", - "description": "1ページあたりに返すアイテム数。", "schema": { "type": "integer", "default": 20, - "maximum": 100 - } + "minimum": 1 + }, + "description": "1 ページあたりの項目数です。サーバーの上限は `100` です。" + }, + { + "name": "keyword", + "in": "query", + "schema": { + "type": "string" + }, + "description": "検索キーワードです。" } ], "responses": { "200": { - "description": "子チャンクのページネーションリスト。", + "description": "子チャンクのリストです。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChildChunk" + }, + "description": "子チャンクのリスト。" + }, + "total": { + "type": "integer", + "description": "子チャンクの合計数です。" + }, + "total_pages": { + "type": "integer", + "description": "合計ページ数です。" + }, + "page": { + "type": "integer", + "description": "現在のページ番号です。" + }, + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + ], + "total": 1, + "total_pages": 1, + "page": 1, + "limit": 20 + } + } } } } @@ -1273,48 +3601,48 @@ "チャンク" ], "summary": "子チャンクを更新", - "description": "特定の子チャンクのコンテンツを更新します。", + "description": "既存の子チャンクのコンテンツを更新します。", "operationId": "updateChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "親セグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." }, { "name": "child_chunk_id", "in": "path", "required": true, - "description": "更新する子チャンクのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "子チャンク ID です。" } ], "requestBody": { @@ -1322,18 +3650,66 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateChildChunkRequest" + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "子チャンクのテキスト内容です。" + } + } } } } }, "responses": { "200": { - "description": "子チャンクの更新に成功しました。", + "description": "子チャンクが正常に更新されました。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 子チャンクインデックスの更新に失敗しました。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } + } } } } @@ -1345,53 +3721,540 @@ "チャンク" ], "summary": "子チャンクを削除", - "description": "特定の子チャンクを削除します。", + "description": "親チャンクから子チャンクを完全に削除します。", "operationId": "deleteChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッジベースのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "親セグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." }, { "name": "child_chunk_id", "in": "path", "required": true, - "description": "削除する子チャンクのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "子チャンク ID です。" } ], "responses": { "204": { - "description": "子チャンクの削除に成功しました。" + "description": "Success." + }, + "400": { + "description": "`invalid_param` : 子チャンクインデックスの削除に失敗しました。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Delete child chunk index failed: {error details}" + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/retrieve": { + "post": { + "tags": [ + "データセット" + ], + "summary": "ナレッジベースからチャンクを取得 / テスト検索", + "description": "ナレッジベースに対して検索クエリを実行し、最も関連性の高いチャンクを取得します。このエンドポイントは本番環境の検索とテスト検索の両方に使用できます。", + "operationId": "retrieveSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "maxLength": 250, + "description": "検索クエリテキストです。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "検索モデルの設定です。このナレッジベースをクエリする際のチャンクの検索方法とランキング方法を制御します。" + }, + "external_retrieval_model": { + "type": "object", + "description": "外部ナレッジベースの検索設定です。", + "properties": { + "top_k": { + "type": "integer", + "description": "返す結果の最大数です。" + }, + "score_threshold": { + "type": "number", + "description": "結果フィルタリング用の最小関連性スコア閾値です。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "スコア閾値フィルタリングが有効かどうかです。" + } + } + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "検索コンテキストに含める添付ファイル ID のリストです。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "検索結果です。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "query": { + "type": "object", + "description": "元のクエリオブジェクトです。", + "properties": { + "content": { + "type": "string", + "description": "クエリテキストです。" + } + } + }, + "records": { + "type": "array", + "items": { + "type": "object", + "properties": { + "segment": { + "type": "object", + "description": "ナレッジベースから一致したチャンクです。", + "properties": { + "id": { + "type": "string", + "description": "チャンクの一意識別子です。" + }, + "position": { + "type": "integer", + "description": "ドキュメント内のチャンクの位置。" + }, + "document_id": { + "type": "string", + "description": "このチャンクが属するドキュメントの ID です。" + }, + "content": { + "type": "string", + "description": "チャンクのテキスト内容です。" + }, + "sign_content": { + "type": "string", + "description": "整合性検証用の署名付きコンテンツハッシュです。" + }, + "answer": { + "type": "string", + "description": "回答コンテンツです。Q&A モードのドキュメントで使用されます。" + }, + "word_count": { + "type": "integer", + "description": "チャンク内容の単語数です。" + }, + "tokens": { + "type": "integer", + "description": "チャンク内容のトークン数です。" + }, + "keywords": { + "type": "array", + "description": "キーワードベースの検索のためにこのチャンクに関連付けられたキーワードです。", + "items": { + "type": "string" + } + }, + "index_node_id": { + "type": "string", + "description": "ベクトルストア内のインデックスノードの ID です。" + }, + "index_node_hash": { + "type": "string", + "description": "インデックスされたコンテンツのハッシュです。変更の検出に使用されます。" + }, + "hit_count": { + "type": "integer", + "description": "このチャンクが検索クエリでマッチした回数です。" + }, + "enabled": { + "type": "boolean", + "description": "このチャンクが検索に対して有効かどうかです。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "チャンクが無効化されたタイムスタンプです。有効な場合は `null` です。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "チャンクを無効化したユーザーの ID です。有効な場合は `null` です。" + }, + "status": { + "type": "string", + "description": "チャンクのインデックスステータスです。" + }, + "created_by": { + "type": "string", + "description": "チャンクを作成したユーザーの ID です。" + }, + "created_at": { + "type": "number", + "description": "作成タイムスタンプ（Unix エポック、秒単位）です。" + }, + "indexing_at": { + "type": "number", + "nullable": true, + "description": "インデックス作成が開始されたタイムスタンプです。まだ開始されていない場合は `null` です。" + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "インデックス作成が完了したタイムスタンプです。まだ完了していない場合は `null` です。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "インデックス作成が失敗した場合のエラーメッセージです。エラーなしの場合は `null` です。" + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "インデックス作成が停止されたタイムスタンプです。停止されていない場合は `null` です。" + }, + "document": { + "type": "object", + "description": "マッチしたチャンクの親ドキュメント情報です。", + "properties": { + "id": { + "type": "string", + "description": "ドキュメントの一意識別子です。" + }, + "data_source_type": { + "type": "string", + "description": "ドキュメントの作成方法です。" + }, + "name": { + "type": "string", + "description": "ドキュメント名です。" + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "ドキュメントタイプの分類です。未設定の場合は `null` です。" + }, + "doc_metadata": { + "type": "object", + "nullable": true, + "description": "ドキュメントのメタデータ値です。メタデータが設定されていない場合は `null` です。" + } + } + } + } + }, + "child_chunks": { + "type": "array", + "description": "階層インデックスを使用している場合、チャンク内でマッチした子チャンクです。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "子チャンクの一意識別子です。" + }, + "content": { + "type": "string", + "description": "子チャンクのテキスト内容です。" + }, + "position": { + "type": "integer", + "description": "親チャンク内の子チャンクの位置です。" + }, + "score": { + "type": "number", + "description": "子チャンクの関連性スコアです。" + } + } + } + }, + "score": { + "type": "number", + "description": "関連性スコアです。" + }, + "tsne_position": { + "type": "object", + "nullable": true, + "description": "t-SNE 可視化の位置です。" + }, + "files": { + "type": "array", + "description": "このチャンクに添付されたファイルです。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "添付ファイルの識別子です。" + }, + "name": { + "type": "string", + "description": "元のファイル名です。" + }, + "size": { + "type": "integer", + "description": "ファイルサイズ（バイト）。" + }, + "extension": { + "type": "string", + "description": "ファイル拡張子。" + }, + "mime_type": { + "type": "string", + "description": "ファイルの MIME タイプ。" + }, + "source_url": { + "type": "string", + "description": "添付ファイルにアクセスする URL です。" + } + } + } + }, + "summary": { + "type": "string", + "nullable": true, + "description": "要約インデックス経由で取得された場合の要約コンテンツです。" + } + } + }, + "description": "一致した検索レコードのリスト。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "query": { + "content": "What is Dify?" + }, + "records": [ + { + "segment": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 1, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "data_source_type": "upload_file", + "name": "guide.txt", + "doc_type": null, + "doc_metadata": null + } + }, + "child_chunks": [], + "score": 0.92, + "tsne_position": null, + "files": [], + "summary": null + } + ] + } + } + } + } + } + }, + "400": { + "description": "- `dataset_not_initialized` : ナレッジベースはまだ初期化中またはインデキシング中です。しばらくお待ちください。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。設定 → モデルプロバイダーで認証情報を完了してください。\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "dataset_not_initialized": { + "summary": "dataset_not_initialized", + "value": { + "status": 400, + "code": "dataset_not_initialized", + "message": "The dataset is still being initialized or indexing. Please wait a moment." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Invalid parameter value." + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 権限が不足しています。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 検索中に内部エラーが発生しました。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "An internal error occurred." + } + } + } + } + } } } } @@ -1399,10 +4262,10 @@ "/datasets/tags": { "post": { "tags": [ - "メタデータ・タグ" + "タグ管理" ], - "summary": "新しいナレッジベースタイプタグを作成", - "description": "ナレッジベースを分類するために使用できる新しいタグを作成します。", + "summary": "ナレッジベースタグを作成", + "description": "ナレッジベースを整理するための新しいタグを作成します。", "operationId": "createKnowledgeTag", "requestBody": { "required": true, @@ -1416,8 +4279,9 @@ "properties": { "name": { "type": "string", - "description": "新しいタグの名前。", - "maxLength": 50 + "minLength": 1, + "maxLength": 50, + "description": "Tag name." } } } @@ -1426,11 +4290,41 @@ }, "responses": { "200": { - "description": "タグの作成に成功しました。", + "description": "タグが正常に作成されました。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "タグ識別子です。" + }, + "name": { + "type": "string", + "description": "タグの表示名です。" + }, + "type": { + "type": "string", + "description": "タグタイプです。ナレッジベースタグの場合は常に `knowledge` です。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "このタグにバインドされたナレッジベースの数です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } } } } @@ -1439,20 +4333,52 @@ }, "get": { "tags": [ - "メタデータ・タグ" + "タグ管理" ], - "summary": "ナレッジベースタイプタグを取得", - "description": "利用可能なすべてのナレッジベースタグのリストを取得します。", + "summary": "ナレッジベースタグリストを取得", + "description": "ワークスペース内のすべてのナレッジベースタグのリストを返します。", "operationId": "getKnowledgeTags", "responses": { "200": { - "description": "タグのリスト。", + "description": "タグのリストです。", "content": { "application/json": { "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "タグ識別子です。" + }, + "name": { + "type": "string", + "description": "タグの表示名です。" + }, + "type": { + "type": "string", + "description": "タグタイプです。ナレッジベースタグの場合は常に `knowledge` です。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "このタグにバインドされたナレッジベースの数です。" + } + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + ] } } } @@ -1462,10 +4388,10 @@ }, "patch": { "tags": [ - "メタデータ・タグ" + "タグ管理" ], - "summary": "ナレッジベースタイプタグ名を変更", - "description": "既存のタグの名前を更新します。", + "summary": "ナレッジベースタグを変更", + "description": "既存のナレッジベースタグの名前を変更します。", "operationId": "updateKnowledgeTag", "requestBody": { "required": true, @@ -1480,13 +4406,13 @@ "properties": { "tag_id": { "type": "string", - "description": "変更するタグのID。", - "format": "uuid" + "description": "更新するタグ ID です。" }, "name": { "type": "string", - "description": "タグの新しい名前。", - "maxLength": 50 + "minLength": 1, + "maxLength": 50, + "description": "新しいタグ名です。" } } } @@ -1495,11 +4421,41 @@ }, "responses": { "200": { - "description": "タグの更新に成功しました。", + "description": "タグが正常に更新されました。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "タグ識別子です。" + }, + "name": { + "type": "string", + "description": "タグの表示名です。" + }, + "type": { + "type": "string", + "description": "タグタイプです。ナレッジベースタグの場合は常に `knowledge` です。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "このタグにバインドされたナレッジベースの数です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } } } } @@ -1508,10 +4464,10 @@ }, "delete": { "tags": [ - "メタデータ・タグ" + "タグ管理" ], - "summary": "ナレッジベースタイプタグを削除", - "description": "タグを削除します。タグはどのナレッジベースにもバインドされていない必要があります。", + "summary": "ナレッジベースタグを削除", + "description": "ナレッジベースタグを完全に削除します。タグ付けされたナレッジベース自体は削除されません。", "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, @@ -1525,8 +4481,7 @@ "properties": { "tag_id": { "type": "string", - "description": "削除するタグのID。", - "format": "uuid" + "description": "削除するタグ ID です。" } } } @@ -1534,8 +4489,8 @@ } }, "responses": { - "200": { - "$ref": "#/components/responses/Success" + "204": { + "description": "Success." } } } @@ -1543,10 +4498,10 @@ "/datasets/tags/binding": { "post": { "tags": [ - "メタデータ・タグ" + "タグ管理" ], - "summary": "データセットをナレッジベースタイプタグにバインド", - "description": "1つまたは複数のタグを特定のナレッジベースにバインドします。", + "summary": "タグをデータセットにバインド", + "description": "ナレッジベースに 1 つ以上のタグをバインドします。ナレッジベースには複数のタグを設定できます。", "operationId": "bindTagsToDataset", "requestBody": { "required": true, @@ -1555,22 +4510,21 @@ "schema": { "type": "object", "required": [ - "target_id", - "tag_ids" + "tag_ids", + "target_id" ], "properties": { - "target_id": { - "type": "string", - "description": "タグをバインドするデータセットのID。", - "format": "uuid" - }, "tag_ids": { "type": "array", - "description": "バインドするタグIDのリスト。", "items": { - "type": "string", - "format": "uuid" - } + "type": "string" + }, + "minItems": 1, + "description": "バインドするタグ ID です。" + }, + "target_id": { + "type": "string", + "description": "ナレッジベース ID です。" } } } @@ -1578,8 +4532,8 @@ } }, "responses": { - "200": { - "$ref": "#/components/responses/Success" + "204": { + "description": "Success." } } } @@ -1587,10 +4541,10 @@ "/datasets/tags/unbinding": { "post": { "tags": [ - "メタデータ・タグ" + "タグ管理" ], - "summary": "データセットとナレッジベースタイプタグのバインドを解除", - "description": "ナレッジベースから特定のタグのバインドを解除します。", + "summary": "タグとデータセットのバインドを解除", + "description": "ナレッジベースからタグバインディングを削除します。", "operationId": "unbindTagFromDataset", "requestBody": { "required": true, @@ -1599,19 +4553,17 @@ "schema": { "type": "object", "required": [ - "target_id", - "tag_id" + "tag_id", + "target_id" ], "properties": { - "target_id": { - "type": "string", - "description": "データセットのID。", - "format": "uuid" - }, "tag_id": { "type": "string", - "description": "バインドを解除するタグのID。", - "format": "uuid" + "description": "バインド解除するタグ ID です。" + }, + "target_id": { + "type": "string", + "description": "ナレッジベース ID です。" } } } @@ -1619,8 +4571,8 @@ } }, "responses": { - "200": { - "$ref": "#/components/responses/Success" + "204": { + "description": "Success." } } } @@ -1628,26 +4580,26 @@ "/datasets/{dataset_id}/tags": { "get": { "tags": [ - "メタデータ・タグ" + "タグ管理" ], - "summary": "データセットにバインドされたタグをクエリ", - "description": "特定のデータセットに現在バインドされているすべてのタグを取得します。", + "summary": "ナレッジベースにバインドされたタグを取得", + "description": "特定のナレッジベースにバインドされたタグのリストを返します。", "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "データセットのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッジベース ID です。" } ], "responses": { "200": { - "description": "データセットにバインドされたタグのリスト。", + "description": "ナレッジベースにバインドされたタグです。", "content": { "application/json": { "schema": { @@ -1660,16 +4612,1268 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "description": "タグ識別子です。" }, "name": { - "type": "string" + "type": "string", + "description": "タグの表示名です。" + } + } + }, + "description": "このナレッジベースにバインドされたタグのリスト。" + }, + "total": { + "type": "integer", + "description": "このナレッジベースにバインドされたタグの合計数です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs" + } + ], + "total": 1 + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata": { + "post": { + "tags": [ + "メタデータ" + ], + "summary": "メタデータフィールドを作成", + "description": "ナレッジベースのカスタムメタデータフィールドを作成します。メタデータフィールドを使用して、構造化された情報でドキュメントにアノテーションを付けることができます。", + "operationId": "createMetadataFieldJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "string", + "number", + "time" + ], + "description": "`string` はテキスト値、`number` は数値、`time` は日付/時刻値です。" + }, + "name": { + "type": "string", + "description": "メタデータフィールド名です。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "メタデータフィールドが正常に作成されました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデータフィールドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデータフィールド名です。" + }, + "type": { + "type": "string", + "description": "メタデータフィールドの種類です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "get": { + "tags": [ + "メタデータ" + ], + "summary": "メタデータフィールドリストを取得", + "description": "ナレッジベースのすべてのメタデータフィールド（カスタムおよび組み込みの両方）の一覧と、各フィールドを使用しているドキュメント数を返します。", + "operationId": "listMetadataFieldsJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + } + ], + "responses": { + "200": { + "description": "ナレッジベースのメタデータフィールドです。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデータフィールドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデータフィールド名です。" + }, + "type": { + "type": "string", + "description": "メタデータフィールドの種類です。" + }, + "count": { + "type": "integer", + "description": "このメタデータフィールドを使用しているドキュメント数です。" + } + } + }, + "description": "メタデータフィールド定義のリスト。" + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "このナレッジベースで組み込みメタデータフィールドが有効かどうかです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "doc_metadata": [ + { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string", + "count": 3 + } + ], + "built_in_field_enabled": true + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/{metadata_id}": { + "patch": { + "tags": [ + "メタデータ" + ], + "summary": "メタデータフィールドを更新", + "description": "カスタムメタデータフィールドの名前を変更します。", + "operationId": "updateMetadataFieldJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + }, + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "メタデータフィールド ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "新しいメタデータフィールド名です。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "メタデータフィールドが正常に更新されました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデータフィールドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデータフィールド名です。" + }, + "type": { + "type": "string", + "description": "メタデータフィールドの種類です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "delete": { + "tags": [ + "メタデータ" + ], + "summary": "メタデータフィールドを削除", + "description": "カスタムメタデータフィールドを完全に削除します。このフィールドを使用しているドキュメントは、該当するメタデータ値を失います。", + "operationId": "deleteMetadataFieldJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + }, + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "メタデータフィールド ID です。" + } + ], + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in": { + "get": { + "tags": [ + "メタデータ" + ], + "summary": "組み込みメタデータフィールドを取得", + "description": "システムが提供する組み込みメタデータフィールドの一覧を返します（例：ドキュメントタイプ、ソース URL）。", + "operationId": "getBuiltInMetadataFieldsJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + } + ], + "responses": { + "200": { + "description": "組み込みメタデータフィールドです。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "fields": { + "type": "array", + "description": "システム提供のメタデータフィールドのリストです。", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "組み込みフィールド識別子です。`document_name` はドキュメントタイトル、`uploader` は作成者、`upload_date` は作成日時、`last_update_date` は最終更新日時、`source` はドキュメントの出典を示します。" + }, + "type": { + "type": "string", + "description": "フィールドのデータ型です。テキスト値の場合は `string`、日時値の場合は `time` です。" } } } + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "fields": [ + { + "name": "document_name", + "type": "string" + }, + { + "name": "uploader", + "type": "string" + }, + { + "name": "upload_date", + "type": "time" + }, + { + "name": "last_update_date", + "type": "time" + }, + { + "name": "source", + "type": "string" + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in/{action}": { + "post": { + "tags": [ + "メタデータ" + ], + "summary": "組み込みメタデータフィールドを更新", + "description": "ナレッジベースの組み込みメタデータフィールドを有効または無効にします。", + "operationId": "toggleBuiltInMetadataFieldJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + }, + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + }, + "description": "`enable` で内蔵メタデータフィールドを有効化、`disable` で無効化します。" + } + ], + "responses": { + "200": { + "description": "組み込みメタデータフィールドの切り替えに成功しました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操作結果です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/metadata": { + "post": { + "tags": [ + "メタデータ" + ], + "summary": "ドキュメントメタデータを一括更新", + "description": "複数のドキュメントのメタデータ値を一括更新します。リクエスト内の各ドキュメントに指定されたメタデータのキーと値のペアが適用されます。", + "operationId": "batchUpdateDocumentMetadataJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "operation_data" + ], + "properties": { + "operation_data": { + "type": "array", + "items": { + "type": "object", + "required": [ + "document_id", + "metadata_list" + ], + "properties": { + "document_id": { + "type": "string", + "description": "メタデータを更新するドキュメントの ID です。" + }, + "metadata_list": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { + "type": "string", + "description": "メタデータフィールド ID です。" + }, + "name": { + "type": "string", + "description": "メタデータフィールド名です。" + }, + "value": { + "description": "メタデータ値。文字列、数値、または `null` を指定できます。" + } + } + } + }, + "partial_update": { + "type": "boolean", + "default": false, + "description": "メタデータを部分的に更新し、未指定フィールドの既存の値を保持するかどうかです。" + } + } }, - "total": { - "type": "integer" + "description": "ドキュメントメタデータの更新操作の配列です。各エントリはドキュメント ID をメタデータのキーと値のペアにマッピングします。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "ドキュメントメタデータが正常に更新されました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操作結果です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/workspaces/current/models/model-types/{model_type}": { + "get": { + "tags": [ + "モデル" + ], + "summary": "利用可能なモデルを取得", + "description": "タイプ別に利用可能なモデルの一覧を取得します。主にナレッジベース設定用の `text-embedding` モデルと `rerank` モデルのクエリに使用します。", + "operationId": "getAvailableModelsJa", + "parameters": [ + { + "name": "model_type", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "text-embedding", + "rerank", + "llm", + "tts", + "speech2text", + "moderation" + ] + }, + "description": "取得するモデルのタイプです。ナレッジベースの設定には、埋め込みモデルの場合は `text-embedding`、リランキングモデルの場合は `rerank` を使用します。" + } + ], + "responses": { + "200": { + "description": "指定された種類で利用可能なモデルです。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "利用可能なモデルを持つモデルプロバイダーのリストです。", + "items": { + "type": "object", + "properties": { + "provider": { + "type": "string", + "description": "モデルプロバイダーの識別子です（例：`openai`、`cohere`）。" + }, + "label": { + "type": "object", + "description": "プロバイダーのローカライズ表示名です。", + "properties": { + "en_US": { + "type": "string", + "description": "英語表示名。" + }, + "zh_Hans": { + "type": "string", + "description": "中国語表示名。" + } + } + }, + "icon_small": { + "type": "object", + "description": "プロバイダーの小アイコンの URL です。", + "properties": { + "en_US": { + "type": "string", + "description": "小アイコン URL。" + } + } + }, + "icon_large": { + "type": "object", + "description": "プロバイダーの大アイコンの URL です。", + "properties": { + "en_US": { + "type": "string", + "description": "大アイコン URL。" + } + } + }, + "status": { + "type": "string", + "description": "プロバイダーのステータスです。認証情報が設定済みで有効な場合は `active` です。" + }, + "models": { + "type": "array", + "description": "このプロバイダーから利用可能なモデルのリストです。", + "items": { + "type": "object", + "properties": { + "model": { + "type": "string", + "description": "モデル識別子です。ナレッジベースの作成または更新時に `embedding_model` の値として使用します。" + }, + "label": { + "type": "object", + "description": "モデルのローカライズ表示名です。", + "properties": { + "en_US": { + "type": "string", + "description": "英語モデル名。" + }, + "zh_Hans": { + "type": "string", + "description": "中国語モデル名。" + } + } + }, + "model_type": { + "type": "string", + "description": "モデルのタイプです。`model_type` パスパラメータと一致します。" + }, + "features": { + "type": "array", + "nullable": true, + "description": "モデルがサポートする機能です。なしの場合は `null` です。", + "items": { + "type": "string" + } + }, + "fetch_from": { + "type": "string", + "description": "モデル定義の取得元です。`predefined-model` は組み込みモデル、`customizable-model` はユーザー設定モデルを示します。" + }, + "model_properties": { + "type": "object", + "description": "`context_size` などのモデル固有のプロパティです。" + }, + "status": { + "type": "string", + "description": "モデルの利用可能ステータスです。使用可能な場合は `active` です。" + } + } + } + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "data": [ + { + "provider": "openai", + "label": { + "en_US": "OpenAI", + "zh_Hans": "OpenAI" + }, + "icon_small": { + "en_US": "https://example.com/openai-small.svg" + }, + "icon_large": { + "en_US": "https://example.com/openai-large.svg" + }, + "status": "active", + "models": [ + { + "model": "text-embedding-3-small", + "label": { + "en_US": "text-embedding-3-small", + "zh_Hans": "text-embedding-3-small" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8191 + }, + "status": "active" + } + ] + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/pipeline/file-upload": { + "post": { + "tags": [ + "ナレッジパイプライン" + ], + "summary": "パイプラインファイルをアップロード", + "description": "ナレッジパイプラインで使用するファイルをアップロードします。`multipart/form-data` で単一ファイルを受け付けます。", + "operationId": "uploadPipelineFileJa", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "アップロードするファイルです。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "ファイルが正常にアップロードされました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "アップロードされたファイルの一意識別子です。" + }, + "name": { + "type": "string", + "description": "元のファイル名です。" + }, + "size": { + "type": "integer", + "description": "ファイルサイズ（バイト）。" + }, + "extension": { + "type": "string", + "description": "ファイル拡張子。" + }, + "mime_type": { + "type": "string", + "description": "ファイルの MIME タイプ。" + }, + "created_by": { + "type": "string", + "description": "ファイルをアップロードしたユーザーの ID。" + }, + "created_at": { + "type": "string", + "description": "アップロードタイムスタンプ（ISO 8601 形式）です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "report.pdf", + "size": 524288, + "extension": "pdf", + "mime_type": "application/pdf", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": "2025-03-06T12:00:00" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : ファイルをアップロードしてください。\n- `filename_not_exists_error` : 指定されたファイル名が存在しません。\n- `too_many_files` : ファイルは 1 つのみ許可されています。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : ファイルサイズの上限を超えています。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 許可されていないファイルタイプです。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/datasource-plugins": { + "get": { + "tags": [ + "ナレッジパイプライン" + ], + "summary": "データソースプラグインリストを取得", + "description": "ナレッジパイプラインで利用可能なすべてのデータソースプラグインを一覧表示します。`is_published` クエリパラメータに応じて公開済みまたはドラフトのプラグインを返します。", + "operationId": "listDatasourcePluginsJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + }, + { + "name": "is_published", + "in": "query", + "schema": { + "type": "boolean", + "default": true + }, + "description": "公開済みまたはドラフトのデータソースプラグインのどちらを取得するかを指定します。`true` は公開済みプラグイン、`false` はドラフトプラグインを返します。" + } + ], + "responses": { + "200": { + "description": "データソースプラグインのリストです。", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "データソースプラグインの一意の識別子です。" + }, + "name": { + "type": "string", + "description": "データソースプラグインの表示名です。" + }, + "type": { + "type": "string", + "description": "データソースプラグインの種類です。" + } + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": [ + { + "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", + "name": "Web Scraper", + "type": "online_document" + } + ] + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": { + "post": { + "tags": [ + "ナレッジパイプライン" + ], + "summary": "データソースノードを実行", + "description": "ナレッジパイプライン内の単一のデータソースノードを実行します。ノードの実行結果を含むストリーミングレスポンスを返します。", + "operationId": "runDatasourceNodeJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + }, + { + "name": "node_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "実行するデータソースノードの ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "is_published" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "データソースノードの入力変数です。" + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "データソースの種類です。" + }, + "credential_id": { + "type": "string", + "nullable": true, + "description": "データソースとの認証に使用する認証情報の ID です。" + }, + "is_published": { + "type": "boolean", + "description": "ノードの公開バージョンとドラフトバージョンのどちらを実行するかを指定します。`true` は公開バージョン、`false` はドラフトを実行します。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "ノード実行イベントを含むストリーミングレスポンスです。", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "ノード実行の進捗と結果を含む Server-Sent Events ストリームです。" + } + } + } + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/run": { + "post": { + "tags": [ + "ナレッジパイプライン" + ], + "summary": "パイプラインを実行", + "description": "ナレッジベースの完全なナレッジパイプラインを実行します。ストリーミングとブロッキングの両方のレスポンスモードをサポートしています。", + "operationId": "runPipelineJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッジベース ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "datasource_info_list", + "start_node_id", + "is_published", + "response_mode" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "パイプラインの入力変数です。" + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "データソースの種類です。" + }, + "datasource_info_list": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "パイプラインが処理するデータソース情報オブジェクトのリストです。" + }, + "start_node_id": { + "type": "string", + "description": "パイプライン実行を開始するノードの ID です。" + }, + "is_published": { + "type": "boolean", + "description": "パイプラインの公開バージョンとドラフトバージョンのどちらを実行するかを指定します。`true` は公開バージョン、`false` はドラフトを実行します。" + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "パイプライン実行のレスポンスモードです。`streaming` はサーバー送信イベントストリームを返し、`blocking` は完了を待って完全な結果を返します。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "パイプライン実行結果。フォーマットは `response_mode` に依存します：ストリーミングは `text/event-stream` を返し、ブロッキングは完全な JSON 結果を返します。", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "パイプライン実行の進捗と結果を含むサーバー送信イベントストリームです。`response_mode` が `streaming` の場合に返されます。" + } + }, + "application/json": { + "schema": { + "type": "object", + "description": "パイプライン実行の完全な結果です。`response_mode` が `blocking` の場合に返されます。", + "additionalProperties": true + }, + "examples": { + "success": { + "summary": "Blocking Response Example", + "value": { + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "data": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "status": "succeeded", + "outputs": {}, + "created_at": 1741267200, + "finished_at": 1741267210 + } + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : アクセスが禁止されています。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッジベースが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "500": { + "description": "`pipeline_run_error` : パイプライン実行に失敗しました。", + "content": { + "application/json": { + "examples": { + "pipeline_run_error": { + "summary": "pipeline_run_error", + "value": { + "status": 500, + "code": "pipeline_run_error", + "message": "Pipeline execution failed: connection timeout" } } } @@ -1681,403 +5885,338 @@ } }, "components": { - "securitySchemes": { - "ApiKeyAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "API_KEY", - "description": "APIキー認証。すべてのAPIリクエストにおいて、Authorization HTTPヘッダーにAPIキーを含めてください。形式：Bearer {API_KEY}。**APIキーの漏洩を防ぐため、APIキーはクライアント側で共有または保存せず、サーバー側で保存することを強くお勧めします。**" - } - }, - "responses": { - "Success": { - "description": "操作に成功しました。", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" - } - } - } - } - } - }, - "FileError": { - "description": "ファイルアップロードに関連する不正なリクエスト。`no_file_uploaded` または `too_many_files` の可能性があります。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "FileTooLarge": { - "description": "ファイルサイズが上限を超えました。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "UnsupportedFileType": { - "description": "ファイルタイプが許可されていません。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "DatasetNameDuplicate": { - "description": "データセット名が既に存在します。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - }, "schemas": { - "ErrorResponse": { + "Dataset": { "type": "object", - "properties": { - "code": { - "type": "string", - "description": "機械読み取り可能なエラーコード。" - }, - "message": { - "type": "string", - "description": "人間が読めるエラーメッセージ。" - }, - "status": { - "type": "integer", - "description": "HTTPステータスコード。" - } - }, - "example": { - "code": "no_file_uploaded", - "message": "ファイルをアップロードしてください。", - "status": 400 - } - }, - "RetrievalModel": { - "type": "object", - "properties": { - "search_method": { - "type": "string", - "description": "取得に使用する検索方法。", - "enum": [ - "hybrid_search", - "semantic_search", - "full_text_search", - "keyword_search" - ] - }, - "reranking_enable": { - "type": "boolean", - "description": "検索結果を改善するためのリランキングモデルを有効にするかどうか。" - }, - "reranking_mode": { - "type": "string", - "description": "リランキングモード。", - "default": "reranking_model", - "enum": [ - "reranking_model", - "weighted_score" - ] - }, - "reranking_model": { - "type": "object", - "description": "リランキングモデルの設定。", - "properties": { - "reranking_provider_name": { - "type": "string", - "description": "リランクモデルのプロバイダー。" - }, - "reranking_model_name": { - "type": "string", - "description": "リランクモデルの名前。" - } - }, - "nullable": true - }, - "top_k": { - "type": "integer", - "description": "返すトップマッチング結果の数。" - }, - "score_threshold_enabled": { - "type": "boolean", - "description": "結果をフィルタするためのスコア閾値を適用するかどうか。" - }, - "score_threshold": { - "type": "number", - "format": "float", - "description": "結果に含まれる最小スコア。", - "nullable": true - }, - "weights": { - "type": "number", - "format": "float", - "description": "ハイブリッド検索モードでのセマンティック検索の重み。", - "nullable": true - } - } - }, - "SummaryIndexSetting": { - "type": "object", - "description": "要約自動生成の設定。", - "properties": { - "enable": { - "type": "boolean", - "description": "要約自動生成を有効にするかどうか。" - }, - "model_name": { - "type": "string", - "description": "要約生成に使用するモデル名。" - }, - "model_provider_name": { - "type": "string", - "description": "要約モデルのプロバイダー。" - }, - "summary_prompt": { - "type": "string", - "description": "要約生成に使用するプロンプトテンプレート。" - } - }, - "required": [ - "enable" - ] - }, - "PreprocessingRule": { - "type": "object", - "description": "ドキュメントコンテンツの前処理ルール。", "properties": { "id": { "type": "string", - "description": "前処理ルールの一意識別子。", - "enum": [ - "remove_extra_spaces", - "remove_urls_emails" - ] + "description": "ナレッジベースの一意識別子です。" }, - "enabled": { + "name": { + "type": "string", + "description": "ナレッジベースの表示名です。ワークスペース内で一意です。" + }, + "description": { + "type": "string", + "description": "ナレッジベースの目的または内容を説明するオプションのテキストです。" + }, + "provider": { + "type": "string", + "description": "プロバイダータイプです。内部管理の場合は `vendor`、外部ナレッジベース接続の場合は `external` です。" + }, + "permission": { + "type": "string", + "description": "このナレッジベースにアクセスできるユーザーを制御します。指定可能な値：`only_me`、`all_team_members`、`partial_members`。" + }, + "data_source_type": { + "type": "string", + "description": "ドキュメントのデータソースタイプです。まだ設定されていない場合は `null` です。" + }, + "indexing_technique": { + "type": "string", + "description": "`high_quality` は埋め込みモデルを使用した精密検索、`economy` はキーワードベースのインデキシングです。" + }, + "app_count": { + "type": "integer", + "description": "現在このナレッジベースを使用しているアプリケーションの数です。" + }, + "document_count": { + "type": "integer", + "description": "ナレッジベース内のドキュメント総数です。" + }, + "word_count": { + "type": "integer", + "description": "全ドキュメントの合計単語数です。" + }, + "created_by": { + "type": "string", + "description": "ナレッジベースを作成したユーザーの ID です。" + }, + "author_name": { + "type": "string", + "description": "作成者の表示名です。" + }, + "created_at": { + "type": "number", + "description": "作成タイムスタンプ（Unix エポック、秒単位）です。" + }, + "updated_by": { + "type": "string", + "description": "ナレッジベースを最後に更新したユーザーの ID です。" + }, + "updated_at": { + "type": "number", + "description": "最終更新タイムスタンプ（Unix エポック、秒単位）です。" + }, + "embedding_model": { + "type": "string", + "description": "インデックス作成に使用される埋め込みモデルの名前です。" + }, + "embedding_model_provider": { + "type": "string", + "description": "埋め込みモデルプロバイダーです。[利用可能なモデルを取得](/api-reference/モデル/利用可能なモデルを取得) で `model_type=text-embedding` を指定した際の `provider` フィールドの値を使用します。" + }, + "embedding_available": { "type": "boolean", - "description": "このルールが有効かどうか。" - } - } - }, - "SegmentationRule": { - "type": "object", - "description": "ドキュメントコンテンツをチャンクにセグメント化するためのルール。", - "properties": { - "separator": { - "type": "string", - "description": "セグメントを分離するために使用するカスタム区切り文字。" + "description": "設定された埋め込みモデルが現在利用可能かどうかです。" }, - "max_tokens": { - "type": "integer", - "description": "単一セグメントで許可される最大トークン数。" - } - } - }, - "SubChunkSegmentationRule": { - "type": "object", - "description": "親チャンクを小さな子チャンクにセグメント化するためのルール（階層モード用）。", - "properties": { - "separator": { - "type": "string", - "description": "サブチャンク化の区切り文字。" - }, - "max_tokens": { - "type": "integer", - "description": "サブチャンクの最大トークン長。" - }, - "chunk_overlap": { - "type": "integer", - "description": "隣接するサブチャンク間の重複トークン数。" - } - } - }, - "ProcessRule": { - "type": "object", - "description": "クリーニングとセグメント化を含む、ドキュメントを処理するためのルールセット。", - "properties": { - "mode": { - "type": "string", - "description": "処理モード：automatic、custom、またはhierarchical。", - "enum": [ - "automatic", - "custom", - "hierarchical" - ] - }, - "rules": { + "retrieval_model_dict": { "type": "object", - "description": "適用する特定のルール、モードが'custom'または'hierarchical'の場合に使用。", + "description": "ナレッジベースの検索設定です。", "properties": { - "pre_processing_rules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PreprocessingRule" + "search_method": { + "type": "string", + "description": "検索に使用する検索方法です。`keyword_search` はキーワードマッチング、`semantic_search` は埋め込みベースの類似度検索、`full_text_search` は全文インデックス検索、`hybrid_search` はセマンティックとキーワードの組み合わせ検索を示します。" + }, + "reranking_enable": { + "type": "boolean", + "description": "リランキングが有効かどうかです。" + }, + "reranking_mode": { + "type": "string", + "nullable": true, + "description": "リランキングモードです。`reranking_model` はモデルベースのリランキング、`weighted_score` はスコアベースの重み付けを示します。リランキングが無効の場合は `null` です。" + }, + "reranking_model": { + "type": "object", + "description": "リランキングモデルの設定です。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "リランキングモデルのプロバイダー名です。" + }, + "reranking_model_name": { + "type": "string", + "description": "リランキングモデル名です。" + } } }, - "segmentation": { - "$ref": "#/components/schemas/SegmentationRule" + "weights": { + "type": "object", + "nullable": true, + "description": "ハイブリッド検索の重み設定です。", + "properties": { + "weight_type": { + "type": "string", + "description": "セマンティック検索とキーワード検索の重みを調整するための戦略です。" + }, + "vector_setting": { + "type": "object", + "description": "セマンティック検索の重み設定です。", + "properties": { + "vector_weight": { + "type": "number", + "description": "セマンティック（ベクトル）検索結果に割り当てられた重みです。" + }, + "embedding_provider_name": { + "type": "string", + "description": "ベクトル検索に使用される埋め込みモデルのプロバイダーです。" + }, + "embedding_model_name": { + "type": "string", + "description": "ベクトル検索に使用される埋め込みモデルの名前です。" + } + } + }, + "keyword_setting": { + "type": "object", + "description": "キーワード検索の重み設定です。", + "properties": { + "keyword_weight": { + "type": "number", + "description": "キーワード検索結果に割り当てられた重みです。" + } + } + } + } }, - "parent_mode": { - "type": "string", - "description": "階層モードでの親チャンクの取得モード。", - "enum": [ - "full-doc", - "paragraph" - ] + "top_k": { + "type": "integer", + "description": "返す結果の最大数です。" }, - "subchunk_segmentation": { - "$ref": "#/components/schemas/SubChunkSegmentationRule" + "score_threshold_enabled": { + "type": "boolean", + "description": "スコア閾値フィルタリングが有効かどうかです。" + }, + "score_threshold": { + "type": "number", + "description": "結果の最小関連性スコアです。`score_threshold_enabled` が `true` の場合にのみ有効です。" } - }, - "nullable": true - } - } - }, - "CreateDocumentByTextRequest": { - "type": "object", - "required": [ - "name", - "text" - ], - "properties": { - "name": { - "type": "string", - "description": "ドキュメントの名前。" + } }, - "text": { - "type": "string", - "description": "ドキュメントの完全なテキストコンテンツ。" + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "サマリーインデックスの設定です。", + "properties": { + "enable": { + "type": "boolean", + "description": "サマリーインデックスが有効かどうかです。" + }, + "model_name": { + "type": "string", + "description": "要約生成に使用されるモデルの名前です。" + }, + "model_provider_name": { + "type": "string", + "description": "要約生成モデルのプロバイダーです。" + }, + "summary_prompt": { + "type": "string", + "description": "要約生成に使用されるプロンプトテンプレートです。" + } + } }, - "indexing_technique": { - "type": "string", - "description": "ドキュメントのインデックス化技術。", - "enum": [ - "high_quality", - "economy" - ] + "tags": { + "type": "array", + "description": "このナレッジベースに関連付けられたタグです。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "タグ識別子です。" + }, + "name": { + "type": "string", + "description": "Tag name." + }, + "type": { + "type": "string", + "description": "タグタイプです。ナレッジベースタグの場合は常に `knowledge` です。" + } + } + } }, "doc_form": { "type": "string", - "description": "インデックス化されたコンテンツの形式。", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] + "description": "ドキュメントのチャンキングモードです。`text_model` は標準テキストチャンキング、`hierarchical_model` は親子構造、`qa_model` は QA ペア抽出を示します。" }, - "doc_language": { + "external_knowledge_info": { + "type": "object", + "nullable": true, + "description": "外部ナレッジベースの接続詳細です。`provider` が `external` の場合に存在します。", + "properties": { + "external_knowledge_id": { + "type": "string", + "description": "外部ナレッジベースの ID です。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "外部ナレッジ API 接続の ID です。" + }, + "external_knowledge_api_name": { + "type": "string", + "description": "外部ナレッジ API の表示名です。" + }, + "external_knowledge_api_endpoint": { + "type": "string", + "description": "外部ナレッジ API のエンドポイント URL です。" + } + } + }, + "external_retrieval_model": { + "type": "object", + "nullable": true, + "description": "外部ナレッジベースの検索設定です。内部ナレッジベースの場合は `null` です。", + "properties": { + "top_k": { + "type": "integer", + "description": "外部ナレッジベースから返す結果の最大数です。" + }, + "score_threshold": { + "type": "number", + "description": "最小関連性スコアのしきい値です。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "スコア閾値フィルタリングが有効かどうかです。" + } + } + }, + "doc_metadata": { + "type": "array", + "description": "ナレッジベースのメタデータフィールド定義です。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデータフィールドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデータフィールド名です。" + }, + "type": { + "type": "string", + "description": "メタデータフィールドの値の種類です。" + } + } + } + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "組み込みメタデータフィールド（例：`document_name`、`uploader`）が有効かどうかです。" + }, + "pipeline_id": { "type": "string", - "description": "ドキュメントの言語、Q&Aモードで重要。", - "example": "Japanese" + "nullable": true, + "description": "カスタム処理パイプラインが設定されている場合のパイプライン ID です。" }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { + "runtime_mode": { "type": "string", - "description": "使用する埋め込みモデルの名前。" + "nullable": true, + "description": "ランタイム処理モードです。" }, - "embedding_model_provider": { + "chunk_structure": { "type": "string", - "description": "埋め込みモデルのプロバイダー。" + "nullable": true, + "description": "チャンク構造の設定です。" }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "要約自動生成の設定。" - } - } - }, - "CreateDocumentByFileRequestData": { - "type": "object", - "description": "ファイルからドキュメントを作成するためのメタデータとルール。", - "properties": { - "original_document_id": { - "type": "string", - "description": "再アップロードまたは修正する既存のドキュメントのID。", - "format": "uuid" + "icon_info": { + "type": "object", + "nullable": true, + "description": "ナレッジベースのアイコン表示設定です。", + "properties": { + "icon_type": { + "type": "string", + "description": "アイコンの種類です。" + }, + "icon": { + "type": "string", + "description": "アイコン識別子または絵文字です。" + }, + "icon_background": { + "type": "string", + "description": "アイコンの背景色です。" + }, + "icon_url": { + "type": "string", + "description": "カスタムアイコン画像の URL です。" + } + } }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] + "is_published": { + "type": "boolean", + "description": "ナレッジベースが公開済みかどうかです。" }, - "doc_form": { - "type": "string", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] + "total_documents": { + "type": "integer", + "description": "ドキュメントの合計数です。" }, - "doc_language": { - "type": "string", - "example": "Japanese" + "total_available_documents": { + "type": "integer", + "description": "有効で利用可能なドキュメントの数です。" }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + "enable_api": { + "type": "boolean", + "description": "このナレッジベースで API アクセスが有効かどうかです。" }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { - "type": "string" - }, - "embedding_model_provider": { - "type": "string" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "要約自動生成の設定。" - } - } - }, - "UpdateDocumentByTextRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "ドキュメントの新しい名前（オプション）。" - }, - "text": { - "type": "string", - "description": "ドキュメントの新しいテキストコンテンツ（オプション）。" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - } - } - }, - "UpdateDocumentByFileRequestData": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "ドキュメントの新しい名前（オプション）。" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + "is_multimodal": { + "type": "boolean", + "description": "マルチモーダルコンテンツ処理が有効かどうかです。" } } }, @@ -2086,1023 +6225,431 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "description": "ドキュメントの一意識別子です。" }, "position": { - "type": "integer" + "type": "integer", + "description": "リスト内のドキュメントの表示位置です。" }, "data_source_type": { - "type": "string" + "type": "string", + "description": "ドキュメントの作成方法です。ファイルアップロードの場合は `upload_file`、Notion インポートの場合は `notion_import` です。" }, "data_source_info": { "type": "object", - "nullable": true + "description": "生のデータソース情報です。`data_source_type` によって異なります。" + }, + "data_source_detail_dict": { + "type": "object", + "description": "ファイル詳細を含む詳細なデータソース情報です。" }, "dataset_process_rule_id": { "type": "string", - "format": "uuid", - "nullable": true + "description": "このドキュメントに適用された処理ルールの ID です。" }, "name": { - "type": "string" + "type": "string", + "description": "ドキュメント名です。" }, "created_from": { - "type": "string" + "type": "string", + "description": "ドキュメントの作成元です。API で作成した場合は `api`、UI で作成した場合は `web` です。" }, "created_by": { "type": "string", - "format": "uuid" + "description": "ドキュメントを作成したユーザーの ID です。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "作成タイムスタンプ（Unix エポック、秒単位）です。" }, "tokens": { - "type": "integer" + "type": "integer", + "description": "ドキュメント内の合計トークン数です。" }, "indexing_status": { - "type": "string" + "type": "string", + "description": "現在のインデックスステータスです。`waiting` はキュー待ち、`parsing` はコンテンツ抽出中、`cleaning` はノイズ除去中、`splitting` はチャンキング中、`indexing` はベクトル構築中、`completed` は準備完了、`error` は失敗、`paused` は手動一時停止を示します。" }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "インデックス作成が失敗した場合のエラーメッセージです。エラーなしの場合は `null` です。" }, "enabled": { - "type": "boolean" + "type": "boolean", + "description": "このドキュメントが検索に対して有効かどうかです。" }, "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true + "type": "number", + "nullable": true, + "description": "ドキュメントが無効化されたタイムスタンプです。有効な場合は `null` です。" }, "disabled_by": { "type": "string", - "format": "uuid", - "nullable": true + "nullable": true, + "description": "ドキュメントを無効化したユーザーの ID です。有効な場合は `null` です。" }, "archived": { - "type": "boolean" + "type": "boolean", + "description": "ドキュメントがアーカイブ済みかどうかです。" }, "display_status": { - "type": "string" + "type": "string", + "description": "`indexing_status` と `enabled` 状態から導出されたユーザー向け表示ステータスです。" }, "word_count": { - "type": "integer" + "type": "integer", + "description": "ドキュメントの合計単語数です。" }, "hit_count": { - "type": "integer" + "type": "integer", + "description": "ドキュメントが検索クエリでマッチした回数です。" }, "doc_form": { - "type": "string" - } - } - }, - "DocumentCreationResponse": { - "type": "object", - "properties": { - "document": { - "$ref": "#/components/schemas/Document" - }, - "batch": { "type": "string", - "description": "インデックス化の進捗を追跡するためのバッチ識別子。" - } - } - }, - "CreateDatasetRequest": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "ナレッジベースの名前。" + "description": "ドキュメントのチャンキングモードです。`text_model` は標準テキストチャンキング、`hierarchical_model` は親子構造、`qa_model` は QA ペア抽出を示します。" }, - "description": { - "type": "string", - "description": "ナレッジベースの説明（オプション）。" - }, - "indexing_technique": { - "type": "string", - "description": "使用するインデックス化技術。", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "description": "ナレッジベースのアクセス権限。", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "provider": { - "type": "string", - "description": "ナレッジベースのプロバイダー。", - "enum": [ - "vendor", - "external" - ] - }, - "external_knowledge_api_id": { - "type": "string", - "description": "外部ナレッジAPIのID（プロバイダーが'external'の場合）。" - }, - "external_knowledge_id": { - "type": "string", - "description": "外部ナレッジのID（プロバイダーが'external'の場合）。" - }, - "embedding_model": { - "type": "string", - "description": "埋め込みモデルの名前。" - }, - "embedding_model_provider": { - "type": "string", - "description": "埋め込みモデルのプロバイダー。" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "要約自動生成の設定。" - } - } - }, - "Dataset": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string", - "nullable": true - }, - "provider": { - "type": "string" - }, - "permission": { - "type": "string" - }, - "data_source_type": { - "type": "string", - "nullable": true - }, - "indexing_technique": { - "type": "string", - "nullable": true - }, - "app_count": { - "type": "integer" - }, - "document_count": { - "type": "integer" - }, - "word_count": { - "type": "integer" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - }, - "updated_by": { - "type": "string", - "format": "uuid" - }, - "updated_at": { - "type": "integer", - "format": "int64" - }, - "embedding_model": { - "type": "string", - "nullable": true - }, - "embedding_model_provider": { - "type": "string", - "nullable": true - }, - "embedding_available": { - "type": "boolean", - "nullable": true - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "このデータセットの要約自動生成設定。", - "nullable": true - } - } - }, - "DatasetListResponse": { - "type": "object", - "properties": { - "data": { + "doc_metadata": { "type": "array", - "items": { - "$ref": "#/components/schemas/Dataset" - } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - }, - "DatasetDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Dataset" - }, - { - "type": "object", - "properties": { - "retrieval_model_dict": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "tags": { - "type": "array", - "items": { - "type": "object" - } - }, - "doc_form": { - "type": "string", - "nullable": true - } - } - } - ] - }, - "UpdateDatasetRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "ナレッジベースの新しい名前。" - }, - "description": { - "type": "string", - "description": "ナレッジベースの新しい説明。" - }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "embedding_model_provider": { - "type": "string" - }, - "embedding_model": { - "type": "string" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "partial_member_list": { - "type": "array", - "description": "'partial_members'権限でアクセスできるメンバーのリスト。", + "description": "このドキュメントに割り当てられたメタデータ値です。", "items": { "type": "object", - "required": [ - "user_id" - ], "properties": { - "user_id": { + "id": { "type": "string", - "description": "メンバーのユーザーID。" + "description": "メタデータフィールドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデータフィールド名です。" + }, + "type": { + "type": "string", + "description": "メタデータフィールドの値の種類です。" + }, + "value": { + "type": "string", + "description": "このドキュメントのメタデータ値。" } } } }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "要約自動生成の設定。" - } - } - }, - "IndexingStatus": { - "type": "object", - "properties": { - "id": { + "summary_index_status": { "type": "string", - "format": "uuid" + "nullable": true, + "description": "このドキュメントの要約インデックスのステータスです。要約インデックスが設定されていない場合は `null` です。" }, - "indexing_status": { - "type": "string" - }, - "processing_started_at": { - "type": "number", - "format": "float" - }, - "parsing_completed_at": { - "type": "number", - "format": "float" - }, - "cleaning_completed_at": { - "type": "number", - "format": "float" - }, - "splitting_completed_at": { - "type": "number", - "format": "float" - }, - "completed_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "paused_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "error": { - "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "completed_segments": { - "type": "integer" - }, - "total_segments": { - "type": "integer" + "need_summary": { + "type": "boolean", + "description": "このドキュメントに要約を生成する必要があるかどうかです。" } } }, - "DocumentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" - } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - }, - "DocumentDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Document" - }, - { - "type": "object", - "properties": { - "dataset_process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "document_process_rule": { - "allOf": [ - { - "$ref": "#/components/schemas/ProcessRule" - }, - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "dataset_id": { - "type": "string" - } - } - } - ] - }, - "indexing_latency": { - "type": "number", - "format": "float", - "nullable": true - }, - "segment_count": { - "type": "integer" - }, - "average_segment_length": { - "type": "integer" - }, - "doc_language": { - "type": "string", - "nullable": true - } - } - } - ] - }, "Segment": { "type": "object", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "チャンクの一意識別子です。" }, "position": { - "type": "integer" + "type": "integer", + "description": "ドキュメント内のチャンクの位置。" }, "document_id": { "type": "string", - "format": "uuid" + "description": "このチャンクが属するドキュメントの ID です。" }, "content": { - "type": "string" + "type": "string", + "description": "チャンクのテキスト内容です。" + }, + "sign_content": { + "type": "string", + "description": "整合性検証用の署名付きコンテンツハッシュです。" }, "answer": { "type": "string", - "nullable": true + "description": "回答コンテンツです。Q&A モードのドキュメントで使用されます。" }, "word_count": { - "type": "integer" + "type": "integer", + "description": "チャンク内容の単語数です。" }, "tokens": { - "type": "integer" + "type": "integer", + "description": "チャンク内容のトークン数です。" }, "keywords": { "type": "array", + "description": "キーワードベースの検索のためにこのチャンクに関連付けられたキーワードです。", "items": { "type": "string" } }, "index_node_id": { - "type": "string" + "type": "string", + "description": "ベクトルストア内のインデックスノードの ID です。" }, "index_node_hash": { - "type": "string" + "type": "string", + "description": "インデックスされたコンテンツのハッシュです。変更の検出に使用されます。" }, "hit_count": { - "type": "integer" + "type": "integer", + "description": "このチャンクが検索クエリでマッチした回数です。" }, "enabled": { - "type": "boolean" + "type": "boolean", + "description": "このチャンクが検索に対して有効かどうかです。" }, "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true + "type": "number", + "nullable": true, + "description": "チャンクが無効化されたタイムスタンプです。有効な場合は `null` です。" }, "disabled_by": { "type": "string", - "format": "uuid", - "nullable": true + "nullable": true, + "description": "チャンクを無効化したユーザーの ID です。有効な場合は `null` です。" }, "status": { - "type": "string" + "type": "string", + "description": "チャンクの現在のインデックスステータスです（例：`completed`、`indexing`、`error`）。" }, "created_by": { "type": "string", - "format": "uuid" + "description": "チャンクを作成したユーザーの ID です。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "作成タイムスタンプ（Unix エポック、秒単位）です。" + }, + "updated_at": { + "type": "number", + "description": "最終更新タイムスタンプ（Unix エポック、秒単位）です。" + }, + "updated_by": { + "type": "string", + "description": "このチャンクを最後に更新したユーザーの ID です。" }, "indexing_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "インデックス作成が開始されたタイムスタンプです。まだ開始されていない場合は `null` です。" }, "completed_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "インデックス作成が完了したタイムスタンプです。まだ完了していない場合は `null` です。" }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "インデックス作成が失敗した場合のエラーメッセージです。エラーなしの場合は `null` です。" }, "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true + "type": "number", + "nullable": true, + "description": "インデックス作成が停止されたタイムスタンプです。停止されていない場合は `null` です。" + }, + "child_chunks": { + "type": "array", + "description": "このチャンクに属する子チャンクです。階層モードのドキュメントにのみ存在します。", + "items": { + "$ref": "#/components/schemas/ChildChunk" + } + }, + "attachments": { + "type": "array", + "description": "このチャンクに添付されたファイルです。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "添付ファイルの識別子です。" + }, + "name": { + "type": "string", + "description": "元のファイル名です。" + }, + "size": { + "type": "integer", + "description": "ファイルサイズ（バイト）。" + }, + "extension": { + "type": "string", + "description": "ファイル拡張子。" + }, + "mime_type": { + "type": "string", + "description": "ファイルの MIME タイプ。" + }, + "source_url": { + "type": "string", + "description": "添付ファイルにアクセスする URL です。" + } + } + } }, "summary": { "type": "string", - "nullable": true - } - } - }, - "CreateSegmentsRequest": { - "type": "object", - "properties": { - "segments": { - "type": "array", - "items": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "チャンクのテキストコンテンツ（Q&Aモードでは質問）。" - }, - "answer": { - "type": "string", - "description": "回答コンテンツ、ドキュメントがQ&Aモードの場合は必須。" - }, - "keywords": { - "type": "array", - "description": "チャンクに関連付けられたキーワード。", - "items": { - "type": "string" - } - } - } - } - } - } - }, - "SegmentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Segment" - } - }, - "doc_form": { - "type": "string" - } - } - }, - "SegmentPaginatedResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/SegmentListResponse" - }, - { - "type": "object", - "properties": { - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - } - ] - }, - "SegmentDetailResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Segment" - }, - "doc_form": { - "type": "string" - } - } - }, - "UpdateSegmentRequest": { - "type": "object", - "properties": { - "segment": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string" - }, - "answer": { - "type": "string" - }, - "keywords": { - "type": "array", - "items": { - "type": "string" - } - }, - "enabled": { - "type": "boolean" - }, - "regenerate_child_chunks": { - "type": "boolean", - "description": "子チャンクを再生成するかどうか（階層モード）。" - } - } - } - } - }, - "RetrieveRequest": { - "type": "object", - "required": [ - "query" - ], - "properties": { - "query": { - "type": "string", - "description": "検索クエリ文字列。" - }, - "retrieval_model": { - "allOf": [ - { - "$ref": "#/components/schemas/RetrievalModel" - }, - { - "type": "object", - "properties": { - "metadata_filtering_conditions": { - "type": "object", - "description": "メタデータに基づいて結果をフィルタする条件。", - "properties": { - "logical_operator": { - "type": "string", - "enum": [ - "and", - "or" - ] - }, - "conditions": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "メタデータフィールドの名前。" - }, - "comparison_operator": { - "type": "string", - "description": "比較の演算子。" - }, - "value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } - ], - "nullable": true, - "description": "比較する値。" - } - } - } - } - } - } - } - } - ] - } - } - }, - "RetrievedSegment": { - "type": "object", - "properties": { - "segment": { - "allOf": [ - { - "$ref": "#/components/schemas/Segment" - }, - { - "type": "object", - "properties": { - "document": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "data_source_type": { - "type": "string" - }, - "name": { - "type": "string" - } - } - } - } - } - ] - }, - "score": { - "type": "number", - "format": "float" - } - } - }, - "RetrieveResponse": { - "type": "object", - "properties": { - "query": { - "type": "object", - "properties": { - "content": { - "type": "string" - } - } - }, - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RetrievedSegment" - } - } - } - }, - "Model": { - "type": "object", - "properties": { - "model": { - "type": "string" - }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "model_type": { - "type": "string" - }, - "features": { - "type": "array", - "items": {}, - "nullable": true - }, - "fetch_from": { - "type": "string" - }, - "model_properties": { - "type": "object", - "properties": { - "context_size": { - "type": "integer" - } - } - }, - "deprecated": { - "type": "boolean" - }, - "status": { - "type": "string" - }, - "load_balancing_enabled": { - "type": "boolean" - } - } - }, - "ModelProvider": { - "type": "object", - "properties": { - "provider": { - "type": "string" - }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "icon_small": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } - }, - "icon_large": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } - }, - "status": { - "type": "string" - }, - "models": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Model" - } + "nullable": true, + "description": "AI が生成したチャンクコンテンツの要約です。要約インデックスが有効でない場合は `null` です。" } } }, "ChildChunk": { "type": "object", - "description": "階層セグメント化における子チャンクを表します。", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "子チャンクの一意識別子です。" }, "segment_id": { "type": "string", - "format": "uuid" + "description": "この子チャンクが属する親チャンクの ID です。" }, "content": { - "type": "string" + "type": "string", + "description": "子チャンクのテキスト内容です。" + }, + "position": { + "type": "integer", + "description": "親チャンク内の子チャンクの位置です。" }, "word_count": { - "type": "integer" - }, - "tokens": { - "type": "integer" - }, - "index_node_id": { - "type": "string" - }, - "index_node_hash": { - "type": "string" - }, - "status": { - "type": "string" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { "type": "integer", - "format": "int64" - }, - "indexing_at": { - "type": "integer", - "format": "int64" - }, - "completed_at": { - "type": "integer", - "format": "int64" - }, - "error": { - "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true - } - } - }, - "CreateChildChunkRequest": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "子チャンクのコンテンツ。" - } - } - }, - "UpdateChildChunkRequest": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "子チャンクの更新されたコンテンツ。" - } - } - }, - "ChildChunkResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ChildChunk" - } - } - }, - "ChildChunkListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ChildChunk" - } - }, - "total": { - "type": "integer" - }, - "total_pages": { - "type": "integer" - }, - "page": { - "type": "integer" - }, - "limit": { - "type": "integer" - } - } - }, - "UploadFileResponse": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "size": { - "type": "integer" - }, - "extension": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri", - "description": "ファイルのプレビューURL。" - }, - "download_url": { - "type": "string", - "format": "uri", - "description": "ファイルのダウンロードURL。" - }, - "mime_type": { - "type": "string" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - } - } - }, - "Tag": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" + "description": "子チャンク内容の単語数です。" }, "type": { "type": "string", - "example": "knowledge" + "description": "子チャンクの作成方法です。システム生成の場合は `automatic`、手動作成の場合は `custom` です。" }, - "binding_count": { - "type": "integer" + "created_at": { + "type": "number", + "description": "作成タイムスタンプ（Unix エポック、秒単位）です。" + }, + "updated_at": { + "type": "number", + "description": "最終更新タイムスタンプ（Unix エポック、秒単位）です。" } } + }, + "RetrievalModel": { + "type": "object", + "required": [ + "search_method", + "reranking_enable", + "top_k", + "score_threshold_enabled" + ], + "properties": { + "search_method": { + "type": "string", + "description": "検索に使用される検索メソッドです。", + "enum": [ + "keyword_search", + "semantic_search", + "full_text_search", + "hybrid_search" + ] + }, + "reranking_enable": { + "type": "boolean", + "description": "リランキングが有効かどうかです。" + }, + "reranking_model": { + "type": "object", + "description": "リランキングモデルの設定です。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "リランキングモデルのプロバイダー名です。" + }, + "reranking_model_name": { + "type": "string", + "description": "リランキングモデル名です。" + } + } + }, + "reranking_mode": { + "type": "string", + "enum": [ + "reranking_model", + "weighted_score" + ], + "nullable": true, + "description": "リランキングモードです。`reranking_enable` が `true` の場合は必須です。" + }, + "top_k": { + "type": "integer", + "description": "返す結果の最大数です。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "スコア閾値フィルタリングが有効かどうかです。" + }, + "score_threshold": { + "type": "number", + "nullable": true, + "description": "結果の最小関連性スコアです。`score_threshold_enabled` が `true` の場合にのみ有効です。" + }, + "weights": { + "type": "object", + "nullable": true, + "description": "ハイブリッド検索の重み設定です。", + "properties": { + "weight_type": { + "type": "string", + "description": "セマンティック検索とキーワード検索の重みを調整するための戦略です。", + "enum": [ + "semantic_first", + "keyword_first", + "customized" + ] + }, + "vector_setting": { + "type": "object", + "description": "セマンティック検索の重み設定です。", + "properties": { + "vector_weight": { + "type": "number", + "description": "セマンティック（ベクトル）検索結果に割り当てられた重みです。" + }, + "embedding_provider_name": { + "type": "string", + "description": "ベクトル検索に使用される埋め込みモデルのプロバイダーです。" + }, + "embedding_model_name": { + "type": "string", + "description": "ベクトル検索に使用される埋め込みモデルの名前です。" + } + } + }, + "keyword_setting": { + "type": "object", + "description": "キーワード検索の重み設定です。", + "properties": { + "keyword_weight": { + "type": "number", + "description": "キーワード検索結果に割り当てられた重みです。" + } + } + } + } + } + } + } + }, + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 認証です。すべての API リクエストにおいて、`Authorization` HTTP ヘッダーに `Bearer ` プレフィックスを付けた API Key を含めてください。例：`Authorization: Bearer {API_KEY}`。**API Key はサーバーサイドに保存し、クライアントサイドで共有・保存しないことを強く推奨します。API Key の漏洩は深刻な結果につながる可能性があります。**" } } } diff --git a/ja/api-reference/openapi_workflow.json b/ja/api-reference/openapi_workflow.json index 16269a90..360f7ce1 100644 --- a/ja/api-reference/openapi_workflow.json +++ b/ja/api-reference/openapi_workflow.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "ワークフローアプリAPI", - "description": "ワークフローアプリケーションは、セッションをサポートせず、翻訳、記事作成、要約AIなどに最適です。", + "description": "ワークフローアプリケーションはセッションなしの動作をサポートし、翻訳、記事作成、要約 AI などに最適です。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "APIのベースURL。{api_base_url}を実際のAPIベースURLに置き換えてください。", + "description": "Workflow App API のベース URL です。{api_base_url} を実際の API ベース URL に置き換えてください。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "実際のAPIベースURL" + "description": "API の実際のベース URL" } } } @@ -26,36 +26,48 @@ "/workflows/run": { "post": { "summary": "ワークフローを実行", - "description": "ワークフローを実行します。公開されたワークフローがないと実行できません。", + "description": "ワークフローを実行します。公開済みのワークフローがないと実行できません。", "operationId": "executeWorkflowJp", - "tags": ["ワークフロー実行"], + "tags": [ + "ワークフロー" + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowExecutionRequestJp" + "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { - "basic_execution_jp": { - "summary": "基本的なワークフロー実行の例", + "streaming_example": { + "summary": "リクエスト例 - ストリーミングモード", "value": { "inputs": { - "query": "このテキストを要約してください：..." + "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", - "user": "workflow_user_jp_001" + "user": "user_workflow_123" } }, - "with_file_array_variable_jp":{ - "summary": "ファイルリスト変数を含む入力の例", + "blocking_example": { + "summary": "リクエスト例 - ブロッキングモード", + "value": { + "inputs": { + "query": "Translate this to French: Hello world" + }, + "response_mode": "blocking", + "user": "user_workflow_456" + } + }, + "with_file_array_variable": { + "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", - "upload_file_id": "アップロードされたファイルID_xyz" + "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", @@ -65,7 +77,7 @@ ] }, "response_mode": "blocking", - "user": "workflow_user_jp_002" + "user": "user_workflow_789" } } } @@ -74,67 +86,606 @@ }, "responses": { "200": { - "description": "ワークフローの実行に成功しました。応答の構造は`response_mode`によって異なります。\n- `blocking`: `application/json`形式で、`WorkflowCompletionResponseJp`オブジェクトが含まれます。\n- `streaming`: `text/event-stream`形式で、`ChunkWorkflowEventJp`イベントストリームが含まれます。", + "description": "リクエスト成功。コンテンツタイプと構造はリクエストの `response_mode` パラメータに依存します。\n\n- `response_mode` が `blocking` の場合、 `application/json` で `WorkflowBlockingResponse` オブジェクトを返します。\n- `response_mode` が `streaming` の場合、 `text/event-stream` で `ChunkWorkflowEvent` オブジェクトのストリームを返します。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowCompletionResponseJp" + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "レスポンス例 - ブロッキングモード", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Bonjour le monde" + }, + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630 + } + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "SSEイベントストリーム。各イベントは'data: 'で始まり、'\\n\\n'で終わります。具体的な構造は`ChunkWorkflowEventJp`を参照してください。" + "description": "サーバー送信イベント (SSE) のストリームです。各イベントは `data: ` プレフィックス付きの JSON オブジェクトで、2 つの改行で終了します。\n\n**SSE パースガイド：**各イベントは `data: ` プレフィックス付きの JSON オブジェクトの行で、`\\n\\n` で終了します。JSON をパースする前に `data: ` プレフィックスを除去してください。JSON 内の `event` フィールドがイベントタイプを決定します。終了イベント（`message_end`、`workflow_finished`、`error` など）を受信するとストリームは終了します。`ping` イベント（10 秒ごとに接続維持のために送信）は無視してください。ストリーム内でエラーイベントが発生しても HTTP ステータスコードは常に `200` です。" + }, + "examples": { + "streamingResponse": { + "summary": "レスポンス例 - ストリーミングモード", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestWorkflowJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルは利用できません。\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : このアプリケーションへの同時リクエストが多すぎます。\n- `rate_limit_error` : アップストリームのモデルプロバイダーのレート制限を超えました。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal Server Error." + } + } + } + } + } + } + } + } + }, + "/workflows/{workflow_id}/run": { + "post": { + "summary": "ID でワークフローを実行", + "description": "ID で指定された特定のワークフローバージョンを実行します。ワークフローの特定の公開バージョンを実行する場合に便利です。", + "operationId": "runWorkflowByIdJa", + "tags": [ + "ワークフロー" + ], + "parameters": [ + { + "name": "workflow_id", + "in": "path", + "required": true, + "description": "実行する特定バージョンのワークフロー ID です。この値は [ワークフローを実行](/api-reference/ワークフロー/ワークフローを実行) のレスポンスおよび [ワークフロー実行詳細を取得](/api-reference/ワークフロー/ワークフロー実行詳細を取得) の `workflow_id` フィールドで返されます。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowExecutionRequest" + }, + "examples": { + "example": { + "summary": "リクエスト例", + "value": { + "inputs": { + "query": "Summarize this article" + }, + "response_mode": "blocking", + "user": "user_workflow_123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "リクエスト成功。コンテンツタイプと構造はリクエストの `response_mode` パラメータに依存します。\n\n- `response_mode` が `blocking` の場合、 `application/json` で `WorkflowBlockingResponse` オブジェクトを返します。\n- `response_mode` が `streaming` の場合、 `text/event-stream` で `ChunkWorkflowEvent` オブジェクトのストリームを返します。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "レスポンス例 - ブロッキングモード", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Article summary here" + }, + "error": null, + "elapsed_time": 2.45, + "total_tokens": 280, + "total_steps": 4, + "created_at": 1705407629, + "finished_at": 1705407631 + } + } + } + } + }, + "text/event-stream": { + "schema": { + "type": "string", + "description": "サーバー送信イベント (SSE) のストリームです。各イベントは `data: ` プレフィックス付きの JSON オブジェクトで、2 つの改行で終了します。\n\n**SSE パースガイド：**各イベントは `data: ` プレフィックス付きの JSON オブジェクトの行で、`\\n\\n` で終了します。JSON をパースする前に `data: ` プレフィックスを除去してください。JSON 内の `event` フィールドがイベントタイプを決定します。終了イベント（`message_end`、`workflow_finished`、`error` など）を受信するとストリームは終了します。`ping` イベント（10 秒ごとに接続維持のために送信）は無視してください。ストリーム内でエラーイベントが発生しても HTTP ステータスコードは常に `200` です。" + } + } + } + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルは利用できません。\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Required parameter missing or invalid.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Workflow is a draft and cannot be executed." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ワークフローが見つかりません。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : このアプリケーションへの同時リクエストが多すぎます。\n- `rate_limit_error` : アップストリームのモデルプロバイダーのレート制限を超えました。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal Server Error." + } + } + } + } + } + } } } }, "/workflows/run/{workflow_run_id}": { "get": { "summary": "ワークフロー実行詳細を取得", - "description": "ワークフロー実行IDに基づいて、ワークフロータスクの現在の実行結果を取得します。", + "description": "ワークフロー実行 ID に基づいて、ワークフロータスクの現在の実行結果を取得します。", "operationId": "getWorkflowRunDetailJp", - "tags": ["ワークフロー実行"], + "tags": [ + "ワークフロー" + ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, - "description": "ワークフロー実行ID。ワークフロー実行の応答またはストリーミングイベントから取得できます。", - "schema": { "type": "string", "format": "uuid" } + "description": "ワークフロー実行 ID です。ワークフロー実行レスポンスまたはストリーミングイベントから取得できます。", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "ワークフロー実行詳細の取得に成功しました。", + "description": "ワークフロー実行の詳細の取得に成功しました。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponseJp" } + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "レスポンス例", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } } } }, - "404": {"description": "ワークフロー実行記録が見つかりません。"} + "400": { + "description": "`not_workflow_app` : アプリモードが API ルートと一致しません。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ワークフロー実行記録が見つかりません。", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } + } + } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "ワークフローログ一覧を取得", + "description": "フィルタリングオプション付きでワークフロー実行ログをページネーションで取得します。", + "operationId": "getWorkflowLogsJp", + "tags": [ + "ワークフロー" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "ログ内を検索するキーワードです。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "実行ステータスでフィルタリングします。", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "1 ページあたりの件数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "この ISO 8601 タイムスタンプ以前に作成されたログをフィルタリングします。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "この ISO 8601 タイムスタンプ以降に作成されたログをフィルタリングします。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "エンドユーザーセッション ID でフィルタリングします。", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "アカウント ID でフィルタリングします。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ワークフローログの取得に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "レスポンス例", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0, + "triggered_from": "app" + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_workflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } } } }, "/workflows/tasks/{task_id}/stop": { "post": { - "summary": "生成を停止 (ワークフロータスク)", - "description": "ワークフロータスクの生成を停止します。ストリーミングモードでのみサポートされています。", + "summary": "ワークフロータスクを停止", + "description": "実行中のワークフロータスクを停止します。`streaming` モードでのみサポートされます。", "operationId": "stopWorkflowTaskGenerationJp", - "tags": ["ワークフロー実行"], + "tags": [ + "ワークフロー" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "タスクID。ストリーミングチャンクの返り値から取得可能。", - "schema": { "type": "string", "format": "uuid" } + "description": "タスク ID です。[ワークフローを実行](/api-reference/ワークフロー/ワークフローを実行) API のストリーミングチャンクレスポンスから取得できます。", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -143,306 +694,3156 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { - "user": { "type": "string", "description": "ユーザー識別子。実行ワークフローAPIに渡されたユーザーと一致する必要があります。" } + "user": { + "type": "string", + "description": "ユーザー識別子です。[ワークフローを実行](/api-reference/ワークフロー/ワークフローを実行) リクエストで渡したユーザーと一致する必要があります。" + } + } + }, + "examples": { + "example": { + "summary": "リクエスト例", + "value": { + "user": "user_workflow_123" + } } } } } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResultJp" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "- `not_workflow_app` : アプリモードが API ルートと一致しません。\n- `invalid_param` : 必須パラメータが不足しているか無効です。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + } } } }, "/files/upload": { "post": { - "summary": "ファイルアップロード (ワークフロー用)", - "description": "ワークフローで使用するファイルをアップロードします。ワークフローでサポートされている任意の形式をサポートします。アップロードされたファイルは、現在のエンドユーザーのみが使用できます。", "operationId": "uploadWorkflowFileJp", - "tags": ["ファイル操作 (ワークフロー)"], + "tags": [ + "ファイル操作" + ], + "summary": "ファイルをアップロード", + "description": "メッセージ送信時に使用するファイルをアップロードします。画像、ドキュメント、音声、動画のマルチモーダル理解が可能です。アップロードされたファイルは現在のエンドユーザーのみが使用できます。", "requestBody": { + "description": "ファイルアップロードリクエスト。multipart/form-data 形式が必要です。", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "file" + ], "properties": { - "file": { "type": "string", "format": "binary", "description": "アップロードするファイル。" }, - "user": { "type": "string", "description": "ユーザー識別子。" } + "file": { + "type": "string", + "format": "binary", + "description": "アップロードするファイル。サポートされるタイプには画像、ドキュメント、音声、動画が含まれます。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。開発者のルールで定義され、アプリケーション内で一意である必要があります。" + } } } } } }, "responses": { - "200": { "description": "ファイルのアップロードに成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } }, - "201": { "description": "ファイルの作成に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } }, - "400": { "$ref": "#/components/responses/BadRequestFileJp" }, - "413": { "$ref": "#/components/responses/FileTooLargeJp" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileJp" }, - "503": { "$ref": "#/components/responses/S3ErrorFileJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + "201": { + "description": "ファイルが正常にアップロードされました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "レスポンス例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : リクエストにファイルが提供されていません。\n- `too_many_files` : 1 回のリクエストにつき 1 ファイルのみ許可されています。\n- `filename_not_exists_error` : アップロードされたファイルにファイル名がありません。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : ファイルサイズの上限を超えています。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 許可されていないファイルタイプです。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { + "get": { + "operationId": "downloadWorkflowFileJa", + "tags": [ + "ファイル操作" + ], + "summary": "ファイルをダウンロード", + "description": "以前[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API 経由でアップロードされたファイルをプレビューまたはダウンロードします。ファイルは、リクエスト元のアプリケーション内のメッセージに属する場合のみアクセスできます。", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "プレビューするファイルの一意の識別子です。[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API のレスポンスから取得します。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "`true` の場合、ブラウザでプレビューする代わりにファイルを添付ファイルとして強制ダウンロードします。", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "ユーザー識別子。エンドユーザーのコンテキストに使用されます。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "生のファイルコンテンツを返します。`Content-Type` ヘッダーはファイルの MIME タイプに設定されます。`as_attachment` が `true` の場合、ファイルは `Content-Disposition: attachment` としてダウンロード形式で返されます。", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : リクエストされたファイルへのアクセスが拒否されました。", + "content": { + "application/json": { + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : リクエストされたファイルが見つかりません。", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } } } }, "/end-users/{end_user_id}": { "get": { - "summary": "エンドユーザー取得", - "description": "IDでエンドユーザーを取得します。\n\n他のAPIがエンドユーザーID（例：ファイルアップロードの `created_by`）を返す場合に利用できます。", "operationId": "getEndUserWorkflowJp", - "tags": ["エンドユーザー"], + "tags": [ + "エンドユーザー" + ], + "summary": "エンドユーザー取得", + "description": "ID を指定してエンドユーザーを取得します。他の API がエンドユーザー ID を返す場合（例：[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード)の `created_by`）に便利です。", "parameters": [ { "name": "end_user_id", "in": "path", "required": true, - "description": "エンドユーザーID。", - "schema": { "type": "string", "format": "uuid" } + "description": "エンドユーザー ID。", + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "エンドユーザーの取得に成功しました。", + "description": "エンドユーザーを正常に取得しました。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailJp" } + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "レスポンス例", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + "404": { + "description": "`end_user_not_found` : エンドユーザーが見つかりません。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } } } }, - "/workflows/logs": { - "get": { - "summary": "ワークフローログを取得", - "description": "ワークフローログを返します。最初のページは最新の`{limit}`メッセージを返します。つまり、逆順です。", - "operationId": "getWorkflowLogsJp", - "tags": ["ワークフロー実行"], - "parameters": [ - { "name": "keyword", "in": "query", "description": "（オプション）検索するキーワード。", "schema": { "type": "string" } }, - { "name": "status", "in": "query", "description": "（オプション）実行ステータス：succeeded, failed, stopped, running。", "schema": { "type": "string", "enum": ["succeeded", "failed", "stopped", "running"] } }, - { "name": "page", "in": "query", "description": "（オプション）現在のページ、デフォルトは1。", "schema": { "type": "integer", "default": 1 } }, - { "name": "limit", "in": "query", "description": "（オプション）1回のリクエストで返すアイテムの数、デフォルトは20。", "schema": { "type": "integer", "default": 20 } } - ], - "responses": { - "200": { "description": "ワークフローログの取得に成功しました。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponseJp" } } } } + "/audio-to-text": { + "post": { + "operationId": "workflowAudioToTextJa", + "tags": [ + "音声・テキスト変換" + ], + "summary": "音声をテキストに変換", + "description": "音声ファイルをテキストに変換します。サポートされる形式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファイルサイズの上限は `30 MB` です。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } } + } + }, + "responses": { + "200": { + "description": "音声からテキストへの変換に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "レスポンス例", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `no_audio_uploaded` : 音声ファイルがアップロードされていません。\n- `provider_not_support_speech_to_text` : モデルプロバイダーが音声認識をサポートしていません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルはこの操作をサポートしていません。\n- `completion_request_error` : 音声認識リクエストに失敗しました。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音声ファイルサイズが上限を超えています。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 許可されていない音声タイプです。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } } + } + }, + "/text-to-audio": { + "post": { + "operationId": "workflowTextToAudioJa", + "tags": [ + "音声・テキスト変換" + ], + "summary": "テキストを音声に変換", + "description": "テキストを音声に変換します。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "リクエスト例", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "生成された音声ファイルを返します。`Content-Type` ヘッダーは音声の MIME タイプ（例：`audio/wav`、`audio/mp3`）に設定されます。`streaming` が `true` の場合、音声はチャンク転送エンコーディングでストリーミングされます。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。\n- `provider_not_initialize` : 有効なモデルプロバイダーの認証情報が見つかりません。\n- `provider_quota_exceeded` : モデルプロバイダーのクォータが使い切られました。\n- `model_currently_not_support` : 現在のモデルはこの操作をサポートしていません。\n- `completion_request_error` : テキスト読み上げリクエストに失敗しました。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部サーバーエラー。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } }, "/info": { "get": { - "summary": "アプリケーションの基本情報を取得 (ワークフロー)", "operationId": "getWorkflowAppInfoJp", - "tags": ["アプリケーション設定 (ワークフロー)"], - "responses": { "200": { "description": "アプリケーションの基本情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリケーションの基本情報を取得", + "description": "このアプリケーションの基本情報（名前、説明、タグ、モード）を取得します。", + "responses": { + "200": { + "description": "アプリケーションの基本情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "レスポンス例", + "value": { + "name": "My Workflow App", + "description": "便利なカスタマーサービスチャットボット。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "workflow", + "author_name": "Dify Team" + } + } + } + } + } + } + } } }, "/parameters": { "get": { - "summary": "アプリケーションのパラメータ情報を取得 (ワークフロー)", "operationId": "getWorkflowAppParametersJp", - "tags": ["アプリケーション設定 (ワークフロー)"], - "responses": { "200": { "description": "アプリケーションのパラメータ情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowAppParametersResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリケーションのパラメータ情報を取得", + "description": "アプリケーションの入力フォーム設定（機能スイッチ、入力パラメータ名、タイプ、デフォルト値）を取得します。", + "responses": { + "200": { + "description": "アプリケーションパラメータ情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "レスポンス例", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : アプリケーションが利用できないか、設定が正しくありません。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getWorkflowAppMetaJa", + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリケーションのメタ情報を取得", + "description": "このアプリケーションのメタデータ（ツールアイコンやその他の設定詳細）を取得します。", + "responses": { + "200": { + "description": "アプリケーションのメタ情報を正常に取得しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "レスポンス例", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } } }, "/site": { "get": { - "summary": "アプリのWebApp設定を取得 (ワークフロー)", "operationId": "getWorkflowWebAppSettingsJp", - "tags": ["アプリケーション設定 (ワークフロー)"], - "responses": { "200": { "description": "WebApp設定情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWebAppSettingsResponseJp" } } } } } + "tags": [ + "アプリケーション設定" + ], + "summary": "アプリの WebApp 設定を取得", + "description": "このアプリケーションの WebApp 設定（サイト設定、テーマ、カスタマイズオプション）を取得します。", + "responses": { + "200": { + "description": "アプリケーションの WebApp 設定。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "レスポンス例", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "便利なカスタマーサービスチャットボット。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このアプリケーションのサイトが見つからないか、ワークスペースがアーカイブされています。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key認証。すべてのAPIリクエストにおいて、Authorization HTTPヘッダーにAPIキーを含めてください（例：Bearer {API_KEY}）。APIキーの漏洩を防ぐため、サーバー側で保存することを強くお勧めします。" } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 認証です。すべての API リクエストにおいて、`Authorization` HTTP ヘッダーに `Bearer ` プレフィックスを付けた API Key を含めてください。例：`Authorization: Bearer {API_KEY}`。**API Key はサーバーサイドに保存し、クライアントサイドで共有・保存しないことを強く推奨します。API Key の漏洩は深刻な結果につながる可能性があります。**" + } }, "responses": { - "BadRequestWorkflowJp": { "description": "リクエストパラメータエラーまたはワークフロー実行失敗。考えられるエラーコード：invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, workflow_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "BadRequestFileJp": { "description": "ファイル操作リクエストエラー。考えられるエラーコード：no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "FileTooLargeJp": { "description": "ファイルが大きすぎます (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "UnsupportedFileTypeFileJp": { "description": "サポートされていないファイルタイプです (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "S3ErrorFileJp": { "description": "S3ストレージサービスエラー。考えられるエラーコード：s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "InternalServerErrorJp": { "description": "内部サーバーエラー。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "SuccessResultJp": { "description": "操作に成功しました。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "EndUserNotFoundJp": { "description": "エンドユーザーが見つかりません。エラーコード：`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } } + "SuccessResult": { + "description": "操作が成功しました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "success" + ], + "description": "操作結果です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス例", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "WorkflowExecutionRequestJp": { + "WorkflowExecutionRequest": { "type": "object", - "required": ["inputs", "response_mode", "user"], + "required": [ + "inputs", + "user" + ], "properties": { "inputs": { "type": "object", - "description": "アプリで定義されたさまざまな変数値の入力を許可します。変数がファイルリストの場合、その値はInputFileObjectWorkflowJpオブジェクトのリストである必要があります。", + "description": "ワークフロー入力変数のキーと値のペアです。ファイル型変数の値は、`type`、`transfer_method`、および `url` または `upload_file_id` を持つファイルオブジェクトの配列である必要があります。アプリが期待する変数名と型については、[アプリケーションのパラメータ情報を取得](/api-reference/アプリケーション設定/アプリケーションのパラメータ情報を取得) レスポンスの `user_input_form` フィールドを参照してください。", "additionalProperties": { - "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectWorkflowJp" } } ] - }, - "example": { "user_query": "これを翻訳してください。", "target_language": "フランス語" } + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "object" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + } + } + ] + } }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "description": "応答の返却モード。streaming (推奨) はSSEに基づきます。blocking は実行完了後に結果を返します (Cloudflareの100秒タイムアウト制限あり)。" }, - "user": { "type": "string", "description": "ユーザー識別子。アプリケーション内で一意である必要があります。" }, - "files": { "type": "array", "items": {"$ref": "#/components/schemas/InputFileObjectWorkflowJp"}, "description": "（オプション）このフィールドはinputs内のファイル型変数に置き換えられました。下位互換性のために残されていますが、inputsを使用することを推奨します。"} + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "レスポンスモードです。同期レスポンスには `blocking`（Cloudflare タイムアウトは `100 s`）、サーバー送信イベントには `streaming` を使用します。省略した場合、デフォルトはブロッキング動作になります。" + }, + "user": { + "type": "string", + "description": "開発者のルールで定義されるユーザー識別子で、アプリケーション内で一意である必要があります。この識別子はデータアクセスの範囲を限定します——ワークフロー実行とファイルは同じ `user` 値でクエリした場合にのみ表示されます。" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + }, + "nullable": true, + "description": "ファイルリストです。ファイルとテキストを組み合わせて入力する場合に適しており、モデルが Vision 機能をサポートしている場合にのみ使用できます。ローカルファイルを添付するには、まず [ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) でアップロードし、返された `id` を `upload_file_id` として `transfer_method: local_file` で使用します。" + } } }, - "InputFileObjectWorkflowJp": { + "InputFileObject": { "type": "object", - "required": ["type", "transfer_method"], + "required": [ + "type", + "transfer_method" + ], "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "ファイルタイプ。document: TXT,MD,PDF等; image: JPG,PNG等; audio: MP3,WAV等; video: MP4,MOV等; custom: その他。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "転送方法。remote_url は画像URL / local_file はファイルアップロード用" }, - "url": { "type": "string", "format": "url", "description": "画像URL（転送方法が remote_url の場合）" }, - "upload_file_id": { "type": "string", "format": "uuid", "description": "アップロードされたファイルID、事前にファイルアップロードAPIで取得する必要があります（転送方法が local_file の場合）" } + "type": { + "type": "string", + "enum": [ + "document", + "image", + "audio", + "video", + "custom" + ], + "description": "ファイルタイプ。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "転送方法です。ファイル URL の場合は `remote_url`、アップロードファイルの場合は `local_file` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファイル URL（`transfer_method` が `remote_url` の場合）です。" + }, + "upload_file_id": { + "type": "string", + "description": "[ファイルをアップロード](/api-reference/ファイル操作/ファイルをアップロード) API から取得したアップロード済みファイル ID です（`transfer_method` が `local_file` の場合に使用）。" + } + } + }, + "WorkflowBlockingResponse": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "進行中の実行のタスク ID です。[ワークフロータスクを停止](/api-reference/ワークフロー/ワークフロータスクを停止) と組み合わせて、実行中のワークフローをキャンセルします。実行中のみ有効です。" + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "このワークフロー実行記録の永続的な識別子です。[ワークフロー実行詳細を取得](/api-reference/ワークフロー/ワークフロー実行詳細を取得) と組み合わせて、実行後に結果を取得します。" + }, + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } + } + }, + "ChunkWorkflowEvent": { + "type": "object", + "required": [ + "event" + ], + "properties": { + "event": { + "type": "string", + "enum": [ + "workflow_started", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "text_chunk", + "text_replace", + "workflow_finished", + "tts_message", + "tts_message_end", + "workflow_paused", + "agent_log", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "error", + "ping" + ], + "description": "ストリーミングイベントの種類。" + } }, - "anyOf": [ + "discriminator": { + "propertyName": "event", + "mapping": { + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "text_chunk": "#/components/schemas/StreamEventTextChunk", + "text_replace": "#/components/schemas/StreamEventTextReplace", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "tts_message": "#/components/schemas/StreamEventTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", + "error": "#/components/schemas/StreamEventError", + "ping": "#/components/schemas/StreamEventPing", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout" + } + } + }, + "StreamEventBase": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "進行中の実行のタスク ID です。[ワークフロータスクを停止](/api-reference/ワークフロー/ワークフロータスクを停止) と組み合わせて、実行中のワークフローをキャンセルします。実行中のみ有効です。" + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "このワークフロー実行記録の永続的な識別子です。[ワークフロー実行詳細を取得](/api-reference/ワークフロー/ワークフロー実行詳細を取得) と組み合わせて、実行後に結果を取得します。" + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format": "uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワークフロー実行 ID です。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "このワークフロー実行の入力変数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワークフロー実行が開始した Unix タイムスタンプです。" + }, + "reason": { + "type": "string", + "description": "ワークフロー開始の理由です。`initial` は新規実行、`resumption` は一時停止状態からの再開を示します。" + } + } + } + } } ] }, - "WorkflowCompletionResponseJp": { - "type": "object", "description": "ブロッキングモードでのワークフロー実行結果。", - "properties": { - "workflow_run_id": { "type": "string", "format": "uuid", "description": "ワークフロー実行の一意のID。" }, - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "data": { "$ref": "#/components/schemas/WorkflowFinishedDataJp" } - } + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ノード実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワークフローグラフ内のノード ID です。" + }, + "node_type": { + "type": "string", + "description": "ノードタイプ（例：`llm`、`code`、`template-transform`）です。" + }, + "title": { + "type": "string", + "description": "ノードの表示名です。" + }, + "index": { + "type": "integer", + "description": "実行シーケンスインデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノードの ID（存在する場合）です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "このノードの入力変数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` データが切り捨てられたかどうかです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ノード実行が開始した Unix タイムスタンプです。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "ノード実行の追加メタデータです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "このノードがイテレーション内で実行される場合の親イテレーション ID です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "このノードがループ内で実行される場合の親ループ ID です。" + } + } + } + } + } + ] }, - "ChunkWorkflowEventJp": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["workflow_started", "node_started", "text_chunk", "node_finished", "workflow_finished", "tts_message", "tts_message_end", "ping"], "description": "イベントタイプ。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "workflow_started": "#/components/schemas/StreamEventWfWorkflowStartedJp", "node_started": "#/components/schemas/StreamEventWfNodeStartedJp", - "text_chunk": "#/components/schemas/StreamEventWfTextChunkJp", "node_finished": "#/components/schemas/StreamEventWfNodeFinishedJp", - "workflow_finished": "#/components/schemas/StreamEventWfWorkflowFinishedJp", "tts_message": "#/components/schemas/StreamEventWfTtsMessageJp", - "tts_message_end": "#/components/schemas/StreamEventWfTtsMessageEndJp", "ping": "#/components/schemas/StreamEventWfPingJp" - }} + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ノード実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワークフローグラフ内のノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ノードの表示名です。" + }, + "index": { + "type": "integer", + "description": "実行シーケンスインデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノードの ID（存在する場合）です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "このノードの入力変数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` データが切り捨てられたかどうかです。" + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ノード実行中に生成された処理データです。" + }, + "process_data_truncated": { + "type": "boolean", + "description": "`process_data` が切り詰められたかどうかです。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ノードからの出力データです。" + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` データが切り詰められたかどうかです。" + }, + "status": { + "type": "string", + "description": "ノードの実行ステータスです。`running` は進行中、`succeeded` は完了、`failed` はエラー、`stopped` は手動停止、`exception` は予期しない障害を示します。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ノードが失敗した場合のエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "経過時間（秒）です。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "description": "トークン使用量を含む実行メタデータです。", + "properties": { + "total_tokens": { + "type": "integer", + "nullable": true, + "description": "このノードで消費された合計トークン数です。" + }, + "total_price": { + "type": "number", + "format": "float", + "nullable": true, + "description": "このノード実行の合計コストです。" + }, + "currency": { + "type": "string", + "nullable": true, + "description": "コストの通貨（例: `USD`）です。" + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ノード実行が開始した Unix タイムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "ノード実行が完了した Unix タイムスタンプです。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "このノードで生成されたファイルです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "このノードがイテレーション内で実行される場合の親イテレーション ID です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "このノードがループ内で実行される場合の親ループ ID です。" + } + } + } + } + } + ] }, - "StreamEventBaseWfJp": { - "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "ワークフロー実行ID。" } } + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ノード実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワークフローグラフ内のノード ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ノードの表示名です。" + }, + "index": { + "type": "integer", + "description": "実行シーケンスインデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノードの ID（存在する場合）です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` データが切り捨てられたかどうかです。" + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ノード実行中に生成された処理データです。" + }, + "process_data_truncated": { + "type": "boolean", + "description": "`process_data` が切り詰められたかどうかです。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` データが切り詰められたかどうかです。" + }, + "status": { + "type": "string", + "description": "リトライ時点のノード実行ステータスです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "リトライをトリガーしたエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "経過時間（秒）です。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "retry_index": { + "type": "integer", + "description": "ゼロ始まりのリトライ回数インデックスです。" + }, + "iteration_id": { + "type": "string", + "nullable": true + }, + "loop_id": { + "type": "string", + "nullable": true + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ノード実行のメタデータです。" + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "実行中にノードが生成したファイルです。" + } + } + } + } + } + ] }, - "StreamEventWfWorkflowStartedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowStartedDataJp" } } } ] }, - "WorkflowStartedDataJp": { "type": "object", "description": "ワークフロー開始イベントの詳細。", "required": ["id", "workflow_id", "sequence_number", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワークフロー実行の一意のID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "関連するワークフローのID。" }, "sequence_number": { "type": "integer", "description": "自己増加シリアル番号、1から始まります。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始時間。" } } }, - "StreamEventWfNodeStartedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeStartedDataJp" } } } ] }, - "NodeStartedDataJp": { "type": "object", "description": "ノード開始イベントの詳細。", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワークフロー実行の一意のID（文脈上、ノード実行IDであるべき）。" }, "node_id": { "type": "string", "format": "uuid", "description": "ノードのID。" }, "node_type": { "type": "string", "description": "ノードのタイプ。" }, "title": { "type": "string", "description": "ノードの名前。" }, "index": { "type": "integer", "description": "実行シーケンス番号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "（オプション）前のノードID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ノードで使用されるすべての前のノード変数の内容。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始のタイムスタンプ。" } } }, - "StreamEventWfTextChunkJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/TextChunkDataJp" } } } ] }, - "TextChunkDataJp": { "type": "object", "description": "テキストフラグメントイベントの詳細。", "required": ["text", "from_variable_selector"], "properties": { "text": { "type": "string", "description": "テキスト内容。" }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "description": "テキスト生成元パス。" } } }, - "StreamEventWfNodeFinishedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeFinishedDataJp" } } } ] }, - "NodeFinishedDataJp": { "type": "object", "description": "ノード終了イベントの詳細。", "required": ["id", "node_id", "index", "status", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ノード実行ID。" }, "node_id": { "type": "string", "format": "uuid", "description": "ノードのID。" }, "index": { "type": "integer", "description": "実行シーケンス番号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "（オプション）前のノードID。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "ノードで使用されるすべての前のノード変数の内容。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "（オプション）ノードプロセスデータ (JSON)。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "（オプション）出力内容 (JSON)。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行のステータス。" }, "error": { "type": "string", "nullable": true, "description": "（オプション）エラー理由。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "（オプション）使用時間（秒）。" }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadataJp" , "nullable": true, "description":"メタデータ"}, "created_at": { "type": "integer", "format": "int64", "description": "開始のタイムスタンプ。" } } }, - "NodeExecutionMetadataJp": { "type": "object", "description": "ノード実行メタデータ。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "（オプション）使用トークン数。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "（オプション）総コスト (floatでdecimalを表現)。" }, "currency": { "type": "string", "nullable": true, "example": "USD", "description": "（オプション）通貨、例：USD / RMB。" } } }, - "StreamEventWfWorkflowFinishedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedDataJp" } } } ] }, - "WorkflowFinishedDataJp": { "type": "object", "description": "ワークフロー終了イベントの詳細。", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワークフロー実行のID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "関連するワークフローのID。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行のステータス。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "（オプション）出力内容 (JSON)。" }, "error": { "type": "string", "nullable": true, "description": "（オプション）エラー理由。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "（オプション）使用時間（秒）。" }, "total_tokens": { "type": "integer", "nullable": true, "description": "（オプション）使用トークン数。" }, "total_steps": { "type": "integer", "default": 0, "description": "総ステップ数、デフォルト0。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始時間。" }, "finished_at": { "type": "integer", "format": "int64", "description": "終了時間。" } } }, - "StreamEventWfTtsMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "format": "byte", "description": "音声合成後のオーディオ、base64テキストコンテンツ。" }, "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } } ] }, - "StreamEventWfTtsMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "description": "終了イベントにはオーディオがないため、これは空の文字列です。" }, "message_id": { "type": "string", "format": "uuid", "description": "一意のメッセージID。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } } ] }, - "StreamEventWfPingJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "type": "object", "description": "接続を維持するために10秒ごとに送信されるPingイベント。" } ] }, - "WorkflowRunDetailResponseJp": { - "type": "object", "description": "ワークフロー実行詳細。", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "ワークフロー実行のID。" }, - "workflow_id": { "type": "string", "format": "uuid", "description": "関連するワークフローのID。" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行のステータス。" }, - "inputs": { "type": "string", "description": "入力内容のJSON文字列。" }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "出力内容のJSONオブジェクト。" }, - "error": { "type": "string", "nullable": true, "description": "エラー理由。" }, - "total_steps": { "type": "integer", "description": "タスクの総ステップ数。" }, - "total_tokens": { "type": "integer", "description": "使用されるトークンの総数。" }, - "created_at": { "type": "integer", "format": "int64", "description": "タスク開始時間。" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "タスク終了時間。" }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "使用される総秒数。" } - } + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ノード実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "イテレーションノード ID です。" + }, + "node_type": { + "type": "string", + "description": "ノードの種類（常に `iteration`）です。" + }, + "title": { + "type": "string", + "description": "イテレーションノードの表示名です。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "イテレーションの入力変数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` データが切り捨てられたかどうかです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "イテレーションのメタデータです。" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] }, - "FileUploadResponseJp": { "type": "object", "description": "ファイルアップロード成功時の応答。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "ファイル名。" }, "size": { "type": "integer", "description": "ファイルサイズ（バイト）。" }, "extension": { "type": "string", "description": "ファイル拡張子。" }, "mime_type": { "type": "string", "description": "ファイルのMIMEタイプ。" }, "created_by": { "type": "string", "format": "uuid", "description": "エンドユーザーID。" }, "created_at": { "type": "integer", "format": "int64", "description": "作成タイムスタンプ。" } } }, - "EndUserDetailJp": { + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "現在のイテレーションインデックス（ゼロ始まり）です。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` データが切り詰められたかどうかです。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "イテレーションの入力変数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` データが切り捨てられたかどうかです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "イテレーションが開始した Unix タイムスタンプです。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "イテレーションの追加メタデータです。" + }, + "status": { + "type": "string", + "description": "イテレーションの完了ステータスです。" + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "トークン使用量を含む実行メタデータです。" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "完了したイテレーションステップ数です。" + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` データが切り捨てられたかどうかです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "現在のループイテレーションインデックス（ゼロベース）です。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "pre_loop_output": { + "description": "前回のループイテレーションからの出力です。", + "nullable": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` データが切り詰められたかどうかです。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ループの入力変数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` データが切り捨てられたかどうかです。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ループの追加メタデータです。" + }, + "status": { + "type": "string", + "description": "ループの完了ステータスです。" + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "トークン使用量を含む実行メタデータです。" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "完了したループイテレーション数です。" + } + } + } + } + } + ] + }, + "StreamEventTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "テキスト内容のチャンクです。" + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "ワークフロー内のテキスト変数のソースパスです。" + } + } + } + } + } + ] + }, + "StreamEventTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "置換テキスト内容です。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } + } + } + ] + }, + "StreamEventTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 エンコードされた MP3 音声チャンク。すべてのチャンクを順番にデコードして連結すると、完全な音声ファイルが生成されます。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "このオーディオチャンクが生成された Unix タイムスタンプです。" + } + } + } + ] + }, + "StreamEventTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "description": "空の文字列。音声ストリームの終了を示します。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "音声ストリームが終了した Unix タイムスタンプです。" + } + } + } + ] + }, + "StreamEventError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "エラーの HTTP ステータスコードです。" + }, + "code": { + "type": "string", + "description": "エラーコード。" + }, + "message": { + "type": "string", + "description": "エラーメッセージ。" + } + } + } + ] + }, + "StreamEventPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "type": "object", + "description": "キープアライブ ping イベントです。追加プロパティはありません。" + } + ] + }, + "WorkflowFinishedData": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "ワークフロー実行 ID です。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "ワークフローの実行ステータスです。`running` は実行中、`succeeded` は正常完了、`failed` は実行エラー、`stopped` は手動停止、`partial-succeeded` は一部のノードが成功し他が失敗、`paused` は人的介入待ちを示します。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ワークフローからの出力データです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワークフローが失敗した場合のエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合計経過時間（秒）です。" + }, + "total_tokens": { + "type": "integer", + "description": "全ノードで消費された合計トークン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワークフローの合計ステップ数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワークフロー実行が作成された Unix タイムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワークフロー実行が完了した Unix タイムスタンプです。" + }, + "created_by": { + "type": "object", + "additionalProperties": true, + "description": "作成者情報です。ストリーミングの `workflow_finished` イベントにのみ存在します。" + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "実行中に発生した例外の数です。ストリーミングの `workflow_finished` イベントにのみ含まれます。" + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "nullable": true, + "description": "ワークフロー実行中に生成されたファイルです。ストリーミングの `workflow_finished` イベントにのみ存在します。" + } } }, - "WorkflowLogsResponseJp": { - "type": "object", "description": "ワークフローログリストの応答。", + "WorkflowRunDetailResponse": { + "type": "object", "properties": { - "page": { "type": "integer", "description": "現在のページ。" }, "limit": { "type": "integer", "description": "1ページあたりのアイテム数。" }, - "total": { "type": "integer", "description": "合計アイテム数。" }, "has_more": { "type": "boolean", "description": "さらにデータがあるかどうか。" }, - "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowLogItemJp" }, "description": "現在のページのデータ。" } + "id": { + "type": "string", + "format": "uuid", + "description": "ワークフロー実行 ID です。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "ワークフローの実行ステータスです。`running` は実行中、`succeeded` は正常完了、`failed` は実行エラー、`stopped` は手動停止、`partial-succeeded` は一部のノードが成功し他が失敗、`paused` は人的介入待ちを示します。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "ワークフロー実行の入力変数です。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ワークフローからの出力データです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワークフローが失敗した場合のエラーメッセージです。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワークフローの合計ステップ数です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合計トークン数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワークフロー実行が作成された Unix タイムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワークフロー実行が完了した Unix タイムスタンプです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "合計経過時間（秒）です。" + } } }, - "WorkflowLogItemJp": { - "type": "object", "description": "単一のワークフローログアイテム。", + "FileUploadResponse": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "ID。" }, - "workflow_run": { "$ref": "#/components/schemas/WorkflowRunSummaryJp", "description": "ワークフロー実行ログ。" }, - "created_from": { "type": "string", "description": "作成元。" }, - "created_by_role": { "type": "string", "description": "作成者の役割。" }, - "created_by_account": { "type": "string", "format": "uuid", "nullable": true, "description": "（オプション）作成者アカウント。" }, - "created_by_end_user": { "$ref": "#/components/schemas/EndUserSummaryJp", "description": "作成者ユーザー。" }, - "created_at": { "type": "integer", "format": "int64", "description": "作成時間。" } + "id": { + "type": "string", + "format": "uuid", + "description": "一意のファイル ID。" + }, + "name": { + "type": "string", + "description": "ファイル名。" + }, + "size": { + "type": "integer", + "description": "ファイルサイズ（バイト）。" + }, + "extension": { + "type": "string", + "nullable": true, + "description": "ファイル拡張子。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "ファイルの MIME タイプ。" + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ファイルをアップロードしたユーザーの ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "アップロードタイムスタンプ（Unix エポック秒）。" + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "ファイルのプレビュー URL。" + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "ファイルのソース URL。" + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "ファイルの元の URL。" + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられたユーザーの ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられたテナントの ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "関連付けられた会話の ID。" + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "ファイルのストレージキー。" + } } }, - "WorkflowRunSummaryJp": { - "type": "object", "description": "ワークフロー実行概要情報。", + "EndUserDetail": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "ID。" }, "version": { "type": "string", "description": "バージョン。" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行ステータス。" }, - "error": { "type": "string", "nullable": true, "description": "（オプション）エラー。" }, - "elapsed_time": { "type": "number", "format": "float", "description": "使用時間（秒）。" }, - "total_tokens": { "type": "integer", "description": "消費トークン数。" }, - "total_steps": { "type": "integer", "description": "実行ステップ長。" }, - "created_at": { "type": "integer", "format": "int64", "description": "開始時間。" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "終了時間。" } + "id": { + "type": "string", + "format": "uuid", + "description": "エンドユーザー ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "テナント ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "アプリケーション ID。" + }, + "type": { + "type": "string", + "description": "エンドユーザーのタイプ。Service API ユーザーの場合は常に `service_api` です。" + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "API リクエストで提供された `user` 識別子です（例：[チャットメッセージを送信](/api-reference/チャットメッセージ/チャットメッセージを送信) の `user` フィールド）。" + }, + "name": { + "type": "string", + "nullable": true, + "description": "エンドユーザー名。" + }, + "is_anonymous": { + "type": "boolean", + "description": "ユーザーが匿名かどうかを示します。元の API リクエストで `user` 識別子が提供されなかった場合、`true` になります。" + }, + "session_id": { + "type": "string", + "description": "セッション識別子。デフォルトは `external_user_id` の値です。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "作成タイムスタンプ。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最終更新タイムスタンプ。" + } } }, - "EndUserSummaryJp": { - "type": "object", "description": "エンドユーザー概要情報。", + "WorkflowLogsResponse": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "タイプ。" }, - "is_anonymous": { "type": "boolean", "description": "匿名かどうか。" }, "session_id": { "type": "string", "description": "セッションID。" } + "page": { + "type": "integer", + "description": "現在のページ番号です。" + }, + "limit": { + "type": "integer", + "description": "1 ページあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "ログエントリの合計数です。" + }, + "has_more": { + "type": "boolean", + "description": "さらにページがあるかどうかです。" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "ワークフローログエントリのリストです。" + } } }, - "AppInfoResponseJp": { "type": "object", "description": "アプリケーションの基本情報。", "properties": { "name": { "type": "string", "description": "アプリケーションの名前。" }, "description": { "type": "string", "description": "アプリケーションの説明。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "アプリケーションのタグ。" } } }, - "WorkflowAppParametersResponseJp": { "type": "object", "description": "ワークフローアプリのパラメータ情報。", "properties": { "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemJp" }, "description": "ユーザー入力フォームの設定。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "画像設定。現在サポートされている画像タイプのみ：png, jpg, jpeg, webp, gif。" } }, "description": "ファイルアップロード設定。" }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer", "description": "ドキュメントアップロードサイズ制限（MB）。" }, "image_file_size_limit": { "type": "integer", "description": "画像ファイルアップロードサイズ制限（MB）。" }, "audio_file_size_limit": { "type": "integer", "description": "オーディオファイルアップロードサイズ制限（MB）。" }, "video_file_size_limit": { "type": "integer", "description": "ビデオファイルアップロードサイズ制限（MB）。" } }, "description": "システムパラメータ。" } } }, - "UserInputFormItemJp": { "type": "object", "description": "ユーザー入力フォーム内のコントロールアイテム。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperJp" }, { "$ref": "#/components/schemas/ParagraphControlWrapperJp" }, { "$ref": "#/components/schemas/SelectControlWrapperJp" } ] }, - "TextInputControlWrapperJp": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlJp" } }, "required":["text-input"] }, - "ParagraphControlWrapperJp": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlJp" } }, "required":["paragraph"] }, - "SelectControlWrapperJp": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlJp" } }, "required":["select"] }, - "TextInputControlJp": { "type": "object", "description": "テキスト入力コントロール。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" } } }, - "ParagraphControlJp": { "type": "object", "description": "段落テキスト入力コントロール。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" } } }, - "SelectControlJp": { "type": "object", "description": "ドロップダウンコントロール。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "変数表示ラベル名。" }, "variable": { "type": "string", "description": "変数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト値。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "オプション値。" } } }, - "WorkflowWebAppSettingsResponseJp": { "type": "object", "description": "ワークフローアプリのWebApp設定。", "properties": { "title": { "type": "string", "description": "WebApp名。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "アイコンタイプ。" }, "icon": { "type": "string", "description": "アイコン内容 (emojiまたは画像URL)。" }, "icon_background": { "type": "string", "description": "16進数形式の背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "アイコンのURL。" }, "description": { "type": "string", "description": "説明。" }, "copyright": { "type": "string", "description": "著作権情報。" }, "privacy_policy": { "type": "string", "description": "プライバシーポリシーのリンク。" }, "custom_disclaimer": { "type": "string", "description": "カスタム免責事項。" }, "default_language": { "type": "string", "description": "デフォルト言語。" }, "show_workflow_steps": { "type": "boolean", "description": "ワークフローの詳細を表示するかどうか。" } } }, - "ErrorResponseJp": { "type": "object", "description": "エラー応答。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTPステータスコード。" }, "code": { "type": "string", "nullable": true, "description": "エラーコード。" }, "message": { "type": "string", "description": "エラーメッセージ。" } } } + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ログエントリ ID です。" + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "ワークフロー実行のソース（例：`service-api`）です。" + }, + "created_by_role": { + "type": "string", + "description": "作成者のロール（例：`end_user`、`account`）です。" + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "管理者ユーザーが作成した場合のアカウント詳細です。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "アカウント ID。" + }, + "name": { + "type": "string", + "description": "アカウント表示名。" + }, + "email": { + "type": "string", + "description": "アカウントメールアドレス。" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ログエントリが作成された Unix タイムスタンプです。" + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ログエントリの追加詳細です。" + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワークフロー実行 ID です。" + }, + "version": { + "type": "string", + "description": "ワークフローバージョン識別子です。" + }, + "status": { + "type": "string", + "description": "ワークフローの実行ステータスです。`running` は実行中、`succeeded` は正常完了、`failed` は実行エラー、`stopped` は手動停止、`partial-succeeded` は一部のノードが成功し他が失敗、`paused` は人的介入待ちを示します。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワークフローが失敗した場合のエラーメッセージです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合計経過時間（秒）です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合計トークン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワークフローの合計ステップ数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワークフロー実行が作成された Unix タイムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワークフロー実行が完了した Unix タイムスタンプです。" + }, + "exceptions_count": { + "type": "integer", + "description": "実行中に発生した例外の数です。" + }, + "triggered_from": { + "type": "string", + "description": "ワークフロー実行をトリガーしたソースです。`debugging` はエディタからのテスト実行、`app` は API またはアプリからの実行を示します。" + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "エンドユーザー ID。" + }, + "type": { + "type": "string", + "description": "エンドユーザーの種類です。" + }, + "is_anonymous": { + "type": "boolean", + "description": "エンドユーザーが匿名かどうかです。" + }, + "session_id": { + "type": "string", + "description": "セッション識別子です。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "音声からテキストへの変換のリクエストボディ。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音声ファイルです。対応形式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。上限：`30 MB`。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "音声認識からの出力テキスト。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "テキストから音声への変換のリクエストボディ。`message_id` または `text` のいずれかを指定してください。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "メッセージ ID です。両方が指定された場合、`text` よりも優先されます。" + }, + "text": { + "type": "string", + "description": "変換する音声コンテンツ。" + }, + "user": { + "type": "string", + "description": "ユーザー識別子。" + }, + "voice": { + "type": "string", + "description": "テキスト読み上げに使用する音声。利用可能な音声は、このアプリに設定された TTS プロバイダーによって異なります。デフォルトには[アプリケーションのパラメータ情報を取得](/api-reference/アプリケーション設定/アプリケーションのパラメータ情報を取得) → `text_to_speech.voice` の `voice` 値を使用してください。" + }, + "streaming": { + "type": "boolean", + "description": "ストリーミングレスポンスを有効にするかどうか。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "アプリケーション名。" + }, + "description": { + "type": "string", + "description": "アプリケーションの説明。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "アプリケーションタグ。" + }, + "mode": { + "type": "string", + "description": "アプリケーションモード。`completion` はテキスト生成アプリ、`chat` は基本チャットアプリ、`agent-chat` はエージェントベースのアプリ、`advanced-chat` は Chatflow アプリ、`workflow` はワークフローアプリです。" + }, + "author_name": { + "type": "string", + "description": "アプリケーション作成者の名前。" + } + } + }, + "WorkflowAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "nullable": true, + "description": "オープニングステートメントのテキストです。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "提案された質問のリストです。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答後の提案質問の設定です。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "音声テキスト変換機能の設定です。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "テキスト音声変換機能の設定です。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + }, + "voice": { + "type": "string", + "description": "TTS 音声識別子。" + }, + "language": { + "type": "string", + "description": "TTS 言語。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "ナレッジ検索の引用リソース設定です。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "アノテーション返信機能の設定です。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "類似コンテンツ機能の設定です。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "コンテンツモデレーション機能の設定です。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機能が有効かどうか。" + } + } + }, + "user_input_form": { + "type": "array", + "items": { + "type": "object", + "oneOf": [ + { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "入力フィールドの表示ラベルです。" + }, + "variable": { + "type": "string", + "description": "ワークフローで使用される変数名です。" + }, + "required": { + "type": "boolean", + "description": "このフィールドが必須かどうかです。" + }, + "default": { + "type": "string", + "description": "入力フィールドのデフォルト値です。" + } + } + } + } + }, + { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "段落フィールドの表示ラベルです。" + }, + "variable": { + "type": "string", + "description": "ワークフローで使用される変数名です。" + }, + "required": { + "type": "boolean", + "description": "このフィールドが必須かどうかです。" + }, + "default": { + "type": "string", + "description": "段落フィールドのデフォルト値です。" + } + } + } + } + }, + { + "title": "Select", + "type": "object", + "properties": { + "select": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "セレクトフィールドの表示ラベルです。" + }, + "variable": { + "type": "string", + "description": "ワークフローで使用される変数名です。" + }, + "required": { + "type": "boolean", + "description": "このフィールドが必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルトで選択される値。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "このフォームコントロールの選択可能な値のリスト。" + } + } + } + } + } + ] + }, + "description": "ユーザー入力フォームの設定です。" + }, + "file_upload": { + "type": "object", + "description": "ファイルアップロードの設定。", + "properties": { + "image": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "画像アップロードが有効かどうか。" + }, + "number_limits": { + "type": "integer", + "description": "アップロード可能な画像の最大数です。" + }, + "detail": { + "type": "string", + "description": "ビジョンモデルの画像詳細レベルです。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "画像アップロードで許可される転送方法です。`remote_url` はファイル URL 経由、`local_file` はアップロード済みファイルを示します。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "システムレベルのパラメータ制限です。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "一般ファイルの最大サイズ（MB）です。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最大画像ファイルサイズ（MB）。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最大音声ファイルサイズ（MB）。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最大動画ファイルサイズ（MB）。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "ワークフロー実行ごとの最大ファイル数です。" + } + } + } + } + }, + "ToolIconDetail": { + "type": "object", + "properties": { + "background": { + "type": "string", + "description": "ツールアイコンの背景色です。" + }, + "content": { + "type": "string", + "description": "絵文字またはアイコンの内容です。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "アイコンの URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "ツールアイコン。キーはツール名です。" + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp タイトル。" + }, + "chat_color_theme": { + "type": "string", + "description": "チャットカラーテーマ。" + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "チャットカラーテーマが反転しているかどうか。" + }, + "icon_type": { + "type": "string", + "description": "使用されるアイコンのタイプ。`emoji` は絵文字アイコン、`image` はアップロードされた画像アイコンです。" + }, + "icon": { + "type": "string", + "description": "アイコンのコンテンツ（絵文字または画像 ID）。" + }, + "icon_background": { + "type": "string", + "description": "アイコンの背景色。" + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "アイコン画像の URL。" + }, + "description": { + "type": "string", + "description": "WebApp の説明。" + }, + "copyright": { + "type": "string", + "description": "著作権テキスト。" + }, + "privacy_policy": { + "type": "string", + "description": "プライバシーポリシー URL。" + }, + "custom_disclaimer": { + "type": "string", + "description": "カスタム免責事項テキスト。" + }, + "default_language": { + "type": "string", + "description": "デフォルト言語コード。" + }, + "show_workflow_steps": { + "type": "boolean", + "description": "ワークフローステップを表示するかどうか。" + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "アプリアイコンを回答アイコンとして使用するかどうか。" + } + } + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "このワークフロー実行記録の永続的な識別子です。[ワークフロー実行詳細を取得](/api-reference/ワークフロー/ワークフロー実行詳細を取得) と組み合わせて、実行後に結果を取得します。" + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "一時停止中のノード ID のリストです。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "一時停止時の部分的な出力です。" + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "一時停止の理由です。" + }, + "status": { + "type": "string", + "description": "ワークフローの実行ステータスです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "作成タイムスタンプ。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合計経過時間（秒）です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合計トークン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行された合計ステップ数です。" + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "ノード実行 ID です。" + }, + "id": { + "type": "string", + "description": "エージェントログエントリ ID です。" + }, + "label": { + "type": "string", + "description": "Log label." + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "親ログエントリ ID です。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "エージェントステップが失敗した場合のエラーメッセージです。" + }, + "status": { + "type": "string", + "description": "エージェントステップのステータスです。" + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "エージェントステップのデータです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "エージェントステップのメタデータです。" + }, + "node_id": { + "type": "string", + "description": "Node ID." + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "Form ID." + }, + "node_id": { + "type": "string", + "description": "入力を要求しているノード ID です。" + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "form_content": { + "type": "string", + "description": "フォーム内容の説明です。" + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "フォーム入力フィールドの定義です。" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "利用可能なユーザーアクションです。" + }, + "display_in_ui": { + "type": "boolean", + "description": "UI にフォームを表示するかどうかです。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "フォーム送信用のトークンです。" + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "フォームフィールドの事前解決されたデフォルト値です。" + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "フォームが期限切れになる Unix タイムスタンプ（秒）です。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "フォーム送信後のレンダリングされた内容です。" + }, + "action_id": { + "type": "string", + "description": "実行されたアクションの ID です。" + }, + "action_text": { + "type": "string", + "description": "実行されたアクションのテキストです。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "フォームが期限切れになった Unix タイムスタンプです。" + } + } + } + } + } + ] + } } }, "tags": [ - { "name": "ワークフロー実行", "description": "ワークフローの実行と管理に関連する操作。" }, - { "name": "ファイル操作 (ワークフロー)", "description": "ワークフロー固有のファイルアップロードとプレビュー操作。" }, - { "name": "エンドユーザー", "description": "エンドユーザー情報に関連する操作。" }, - { "name": "アプリケーション設定 (ワークフロー)", "description": "ワークフローアプリのアプリケーション設定と情報。" } + { + "name": "ワークフロー", + "description": "ワークフローの実行と管理のための操作です。" + }, + { + "name": "ファイル操作", + "description": "ファイルのアップロードとダウンロードの操作です。" + }, + { + "name": "エンドユーザー", + "description": "エンドユーザー情報に関連する操作です。" + }, + { + "name": "音声・テキスト変換", + "description": "音声からテキストおよびテキストから音声への変換です。" + }, + { + "name": "アプリケーション設定", + "description": "アプリケーションの設定、パラメータ、メタデータです。" + } ] -} \ No newline at end of file +} diff --git a/zh/api-reference/openapi_chat.json b/zh/api-reference/openapi_chat.json index 296d1855..ac6d02e8 100644 --- a/zh/api-reference/openapi_chat.json +++ b/zh/api-reference/openapi_chat.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "对话型应用 API", - "description": "对话应用支持会话持久化，可将之前的聊天记录作为上下文进行回答，可适用于聊天/客服 AI 等。", + "description": "对话型应用支持会话持久化，允许将之前的聊天记录作为上下文进行回复。适用于聊天机器人、客服 AI 等场景。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API 的基础 URL。请将 {api_base_url} 替换为你的应用提供的实际 API 基础 URL。", + "description": "对话型应用 API 的基础 URL。请将 {api_base_url} 替换为你的应用实际提供的 API 基础 URL。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "实际的 API 基础 URL" + "description": "API 的实际基础 URL" } } } @@ -26,27 +26,29 @@ "/chat-messages": { "post": { "summary": "发送对话消息", - "description": "创建会话消息。", + "description": "向应用发送请求。", "operationId": "sendBasicChatMessageCn", - "tags": ["对话消息"], + "tags": [ + "对话消息" + ], "requestBody": { "description": "发送对话消息的请求体。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BasicChatRequestCn" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file": { - "summary": "包含文件和自定义输入的流式请求示例", + "streaming_example": { + "summary": "请求示例 - 流式模式", "value": { "inputs": { - "name": "dify" + "city": "San Francisco" }, - "query": "iPhone 13 Pro Max 的规格是什么？", + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "conversation_id": "", "user": "abc-123", "files": [ { @@ -56,57 +58,15 @@ } ] } - } - } - } - } - }, - "responses": { - "200": { - "description": "请求成功。响应的内容类型和结构取决于请求中的 `response_mode` 参数。\n- 当 `response_mode` 为 `blocking` 时，返回 `application/json` 格式的 `ChatCompletionResponseCn` 对象。\n- 当 `response_mode` 为 `streaming` 时，返回 `text/event-stream` 格式的 `ChunkBasicChatEventCn` 对象流式序列。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChatCompletionResponseCn" - } - }, - "text/event-stream": { - "schema": { - "type": "string", - "description": "SSE 事件流。每个事件以 'data: ' 开头，以 '\\n\\n' 结尾。具体结构请参见 `ChunkBasicChatEventCn`。" - } - } - } - }, - "400": { "$ref": "#/components/responses/BadRequestGenericCn" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } - } - } - }, - "/files/upload": { - "post": { - "summary": "上传文件", - "description": "上传文件（目前仅支持图片）并在发送消息时使用，可实现图文多模态理解。支持 png, jpg, jpeg, webp, gif 格式。上传的文件仅供当前终端用户使用。", - "operationId": "uploadBasicChatFileCn", - "tags": ["文件操作"], - "requestBody": { - "description": "文件上传请求。需使用 `multipart/form-data` 进行请求。", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "要上传的文件。" - }, - "user": { - "type": "string", - "description": "用户标识，必须和发送消息接口传入 user 保持一致。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。" + }, + "blocking_example": { + "summary": "请求示例 - 阻塞模式", + "value": { + "inputs": {}, + "query": "What are the specs of the iPhone 13 Pro Max?", + "response_mode": "blocking", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "user": "abc-123" } } } @@ -115,183 +75,195 @@ }, "responses": { "200": { - "description": "文件上传成功。", + "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `ChatCompletionResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkChatEvent` 对象流。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FileUploadResponseCn" + "$ref": "#/components/schemas/ChatCompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "响应示例 - 阻塞模式", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "chat", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + } } - } - } - }, - "201": { - "description": "文件创建成功 (备选成功状态码)。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseCn" } } } - }, - "400": { "$ref": "#/components/responses/BadRequestFileCn" }, - "413": { "$ref": "#/components/responses/FileTooLargeCn" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileCn" }, - "503": { "$ref": "#/components/responses/S3ErrorFileCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "获取终端用户", - "description": "通过 ID 获取终端用户信息。\n\n当其他 API 返回终端用户 ID（例如文件上传接口返回的 `created_by`）时，可使用该接口查询对应的终端用户信息。", - "operationId": "getEndUserChatCn", - "tags": ["终端用户"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "终端用户 ID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "responses": { - "200": { - "description": "成功获取终端用户信息。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailCn" } - } - } - }, - "404": { "$ref": "#/components/responses/EndUserNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } - } - } - }, - "/files/{file_id}/preview": { - "get": { - "summary": "文件预览", - "description": "预览或下载已上传的文件。此端点允许你访问之前通过文件上传API上传的文件。文件只能在所属的应用程序消息内访问。", - "operationId": "previewBasicChatFileCn", - "tags": ["文件操作"], - "parameters": [ - { - "name": "file_id", - "in": "path", - "required": true, - "description": "要预览的文件的唯一标识符，从文件上传API响应中获取。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "as_attachment", - "in": "query", - "required": false, - "description": "是否强制作为附件下载文件。默认为`false`（在浏览器中预览）。", - "schema": { - "type": "boolean", - "default": false - } - } - ], - "responses": { - "200": { - "description": "文件内容成功返回。根据文件类型和请求参数设置响应头。", - "content": { - "image/png": { + }, + "text/event-stream": { "schema": { "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - }, - "headers": { - "Content-Type": { - "description": "文件的MIME类型", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "文件大小（字节）（如果可用）", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "如果as_attachment=true，则设置为'attachment'", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "用于性能的缓存头", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "对于音频/视频文件设置为'bytes'", - "schema": { - "type": "string", - "example": "bytes" + "description": "服务器发送事件 (SSE) 流。每个事件是一个以 `data: ` 为前缀的 JSON 对象，以两个换行符终止。\n\n**SSE 解析指南：**每个事件是一行以 `data: ` 为前缀的 JSON 对象，以 `\\n\\n` 终止。解析 JSON 前先去除 `data: ` 前缀。JSON 内的 `event` 字段决定事件类型。当收到终止事件（如 `message_end`、`workflow_finished` 或 `error`）时流结束。忽略 `ping` 事件（每 10 秒发送一次以保持连接活跃）。注意即使流中出现错误事件，HTTP 状态码仍为 `200`。" + }, + "examples": { + "streamingResponseBasic": { + "summary": "Response Example - Streaming (Basic)", + "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" + }, + "streamingResponseAgent": { + "summary": "Response Example - Streaming (Agent)", + "value": "data: {\"event\": \"agent_thought\", \"id\": \"agent_thought_id_1\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"position\": 1, \"thought\": \"Thinking about calling a tool...\", \"tool\": \"dalle3\", \"tool_input\": \"{\\\"dalle3\\\": {\\\"prompt\\\": \\\"a cute cat\\\"}}\", \"created_at\": 1705395332} data: {\"event\": \"message_file\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"conversation_id\": \"conv123\"} data: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333} data: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}" + } } } } }, "400": { - "description": "错误请求。可能的错误代码:\n- `invalid_param`: 异常参数输入。", + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 文本生成失败。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } - } - } - }, - "403": { - "description": "禁止访问。可能的错误代码:\n- `file_access_denied`: 文件访问被拒绝或文件不属于当前应用程序。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "conversation_completed": { + "summary": "conversation_completed", + "value": { + "status": 400, + "code": "conversation_completed", + "message": "The conversation has ended. Please start a new conversation." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } } } }, "404": { - "description": "未找到。可能的错误代码:\n- `file_not_found`: 文件未找到或已被删除。", + "description": "`not_found` : 会话不存在。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 上游模型提供商的速率限制已超出。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } } } }, "500": { - "description": "内部服务器错误。", + "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -301,16 +273,20 @@ "/chat-messages/{task_id}/stop": { "post": { "summary": "停止响应", - "description": "停止生成对话消息。仅支持流式模式。", + "description": "停止聊天消息生成任务。仅在 `streaming` 模式下支持。", "operationId": "stopBasicChatMessageGenerationCn", - "tags": ["对话消息"], + "tags": [ + "对话消息" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "任务 ID，可在流式返回 Chunk 中获取。", - "schema": { "type": "string", "format": "uuid" } + "description": "任务 ID，可以从 [发送对话消息](/api-reference/对话消息/发送对话消息) API 的流式分块返回中获取。", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -319,66 +295,45 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { "user": { "type": "string", - "description": "用户标识，必须和发送消息接口传入 user 保持一致。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。" + "description": "用户标识符，必须和发送消息接口传入的 user 保持一致。" + } + } + }, + "examples": { + "example": { + "summary": "请求示例", + "value": { + "user": "abc-123" } } } } } }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "消息反馈（点赞）", - "description": "消息终端用户反馈、点赞，方便应用开发者优化输出预期。", - "operationId": "postBasicChatMessageFeedbackCn", - "tags": ["消息反馈"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestCn" } - } - } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } - } - } - }, - "/app/feedbacks": { - "get": { - "summary": "获取APP的消息点赞和反馈", - "description": "获取应用的终端用户反馈、点赞。", - "operationId": "getBasicChatAppFeedbacksCn", - "tags": ["消息反馈"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamCn" } - ], "responses": { "200": { - "description": "成功获取应用的反馈列表。", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseCn" } + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } } } } @@ -388,54 +343,547 @@ "/messages/{message_id}/suggested": { "get": { "summary": "获取下一轮建议问题列表", - "description": "获取当前消息的下一轮建议问题列表。", + "description": "获取当前消息的下一步建议问题。", "operationId": "getBasicChatSuggestedQuestionsCn", - "tags": ["对话消息"], + "tags": [ + "对话消息" + ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string" + } }, - { "$ref": "#/components/parameters/UserQueryParamCn" } + { + "name": "user", + "in": "query", + "required": true, + "description": "用户标识符。", + "schema": { + "type": "string" + } + } ], "responses": { "200": { - "description": "成功获取建议问题列表。", + "description": "成功获取建议问题。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponseCn" } + "schema": { + "$ref": "#/components/schemas/SuggestedQuestionsResponse" + }, + "examples": { + "suggestedQuestions": { + "summary": "响应示例", + "value": { + "result": "success", + "data": [ + "What colors does the iPhone 13 Pro Max come in?", + "How does the battery compare to iPhone 12?", + "What is the price range?" + ] + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `bad_request` : 建议问题功能已禁用。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Suggested Questions Is Disabled." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 消息不存在。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } } } }, - "/messages": { - "get": { - "summary": "获取会话历史消息", - "description": "滚动加载形式返回历史聊天记录，第一页返回最新 `limit` 条，即倒序返回。", - "operationId": "getBasicChatConversationHistoryCn", - "tags": ["会话管理"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdQueryParamCn" }, - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { - "name": "first_id", - "in": "query", - "description": "当前页第一条聊天记录的 ID，默认 null。", - "schema": { "type": "string", "format": "uuid", "nullable": true } + "/files/upload": { + "post": { + "summary": "上传文件", + "description": "上传文件用于发送消息时使用，支持图片、文档、音频和视频的多模态理解。上传的文件仅供当前终端用户使用。", + "operationId": "uploadBasicChatFileCn", + "tags": [ + "文件操作" + ], + "requestBody": { + "description": "文件上传请求。需要 multipart/form-data 格式。", + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "要上传的文件。支持的类型包括图片、文档、音频和视频。" + }, + "user": { + "type": "string", + "description": "用户标识符，由开发者定义的规则生成，必须在应用内唯一。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "文件上传成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Cn" } + "400": { + "description": "- `no_file_uploaded` : 请求中未提供文件。\n- `too_many_files` : 每次请求仅允许上传一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : 文件大小超出限制。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 不允许的文件类型。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { + "get": { + "summary": "下载文件", + "description": "预览或下载之前通过[上传文件](/api-reference/文件操作/上传文件) API 上传的文件。仅可访问属于请求应用内消息的文件。", + "operationId": "previewBasicChatFileCn", + "tags": [ + "文件操作" + ], + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "要预览的文件唯一标识符，从 [上传文件](/api-reference/文件操作/上传文件) API 响应中获取。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "如果为 `true`，则强制文件以附件形式下载，而不是在浏览器中预览。", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符，用于终端用户上下文。", + "schema": { + "type": "string" + } + } ], "responses": { "200": { - "description": "成功获取会话历史消息。", + "description": "返回原始文件内容。`Content-Type` 头设置为文件的 MIME 类型。如果 `as_attachment` 为 `true`，文件将以 `Content-Disposition: attachment` 方式作为下载返回。", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : 拒绝访问请求的文件。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/BasicConversationHistoryResponseCn" } + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : 未找到请求的文件。", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "summary": "获取终端用户信息", + "description": "根据 ID 获取终端用户信息。当其他 API 返回终端用户 ID（例如[上传文件](/api-reference/文件操作/上传文件)返回的 `created_by`）时很有用。", + "operationId": "getEndUserChatCn", + "tags": [ + "终端用户" + ], + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "终端用户 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "成功获取终端用户。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "响应示例", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : 未找到终端用户。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/messages/{message_id}/feedbacks": { + "post": { + "summary": "提交消息反馈", + "description": "提交消息反馈。终端用户可以对消息评价 `like` 或 `dislike`，并可选择提供文字反馈。将 `rating` 设为 `null` 可撤销之前提交的反馈。", + "operationId": "postBasicChatMessageFeedbackCn", + "tags": [ + "消息反馈" + ], + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "消息 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "请求示例", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : 消息不存在。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/app/feedbacks": { + "get": { + "summary": "获取应用的消息反馈", + "description": "获取此应用中所有消息反馈的分页列表，包括终端用户和管理员反馈。", + "operationId": "getBasicChatAppFeedbacksCn", + "tags": [ + "消息反馈" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "分页页码。", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页记录数。", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } + } + ], + "responses": { + "200": { + "description": "应用反馈列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "rating": "like", + "content": "The response accurately answered my question about product specifications.", + "from_source": "user", + "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "from_account_id": null, + "created_at": "2025-01-16T14:30:29Z", + "updated_at": "2025-01-16T14:30:29Z" + }, + { + "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", + "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", + "rating": "dislike", + "content": "The answer was too vague and did not address the specific pricing question.", + "from_source": "user", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", + "from_account_id": null, + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" + } + ] + } + } + } } } } @@ -445,21 +893,616 @@ "/conversations": { "get": { "summary": "获取会话列表", - "description": "获取当前用户的会话列表，默认返回最近的 20 条。", + "description": "获取当前用户的会话列表，按最近活跃时间排序。", "operationId": "getBasicChatConversationsListCn", - "tags": ["会话管理"], + "tags": [ + "会话管理" + ], "parameters": [ - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { "$ref": "#/components/parameters/LastIdQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" }, - { "$ref": "#/components/parameters/SortByQueryParamCn" } + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符。", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "当前页最后一条记录的 ID（用于分页）。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "返回的记录数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "sort_by", + "in": "query", + "required": false, + "description": "排序字段。使用 '-' 前缀表示降序。", + "schema": { + "type": "string", + "enum": [ + "created_at", + "-created_at", + "updated_at", + "-updated_at" + ], + "default": "-updated_at" + } + } ], "responses": { "200": { "description": "成功获取会话列表。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationsListResponseCn" } + "schema": { + "$ref": "#/components/schemas/ConversationsListResponse" + }, + "examples": { + "conversationsList": { + "summary": "响应示例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 上一个会话不存在（无效的 `last_id`）。", + "content": { + "application/json": { + "examples": { + "last_conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Last Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/messages": { + "get": { + "summary": "获取会话历史消息", + "description": "以滚动加载的格式返回历史聊天记录，首页返回最新的 `limit` 条消息，即按时间倒序排列。", + "operationId": "getBasicChatConversationHistoryCn", + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符。", + "schema": { + "type": "string" + } + }, + { + "name": "first_id", + "in": "query", + "required": false, + "description": "当前页第一条聊天记录的 ID。默认为 `null`（获取最新消息）。获取后续页面时，使用当前列表中第一条消息的 ID 来获取更早的消息。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "每次请求返回的聊天历史消息数量。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "成功获取会话历史。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "响应示例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "parent_message_id": null, + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "status": "normal", + "error": null, + "message_files": [], + "feedback": { + "rating": "like" + }, + "retriever_resources": [], + "agent_thoughts": [], + "created_at": 1705407629, + "extra_contents": [] + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 会话不存在。\n- `not_found` : 第一条消息不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "first_message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "First Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables": { + "get": { + "summary": "获取对话变量", + "description": "从特定会话中获取变量。", + "operationId": "getBasicChatConversationVariablesCn", + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符。", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "当前页最后一条记录的 ID（用于分页）。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "返回的记录数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "variable_name", + "in": "query", + "required": false, + "description": "按指定名称筛选变量。", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + } + ], + "responses": { + "200": { + "description": "成功获取会话变量。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariablesResponse" + }, + "examples": { + "conversationVariables": { + "summary": "响应示例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "dark_mode", + "description": "用户偏好设置", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会话不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/name": { + "post": { + "summary": "重命名会话", + "description": "重命名会话或自动生成名称。会话名称用于在支持多会话的客户端上显示。", + "operationId": "renameBasicChatConversationCn", + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationRenameRequest" + }, + "examples": { + "renameExample": { + "summary": "请求示例", + "value": { + "name": "iPhone Specs Chat", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "会话重命名成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationListItem" + }, + "examples": { + "renamedConversation": { + "summary": "响应示例", + "value": { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会话不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables/{variable_id}": { + "put": { + "summary": "更新对话变量", + "description": "更新特定会话变量的值。值必须与预期类型匹配。", + "operationId": "updateChatConversationVariableZh", + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "variable_id", + "in": "path", + "required": true, + "description": "Variable ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableUpdateRequest" + }, + "examples": { + "updateStringVariable": { + "summary": "请求示例", + "value": { + "value": "new value", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "变量更新成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableItem" + }, + "examples": { + "updatedVariable": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "new value", + "description": "用户偏好设置", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `bad_request` : 变量值类型不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "type_mismatch": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Value type mismatch: expected string, got integer." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 会话不存在。\n- `not_found` : 会话变量不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "variable_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Variable Not Exists." + } + } + } } } } @@ -469,91 +1512,349 @@ "/conversations/{conversation_id}": { "delete": { "summary": "删除会话", - "description": "删除一个指定的会话。", + "description": "删除会话。", "operationId": "deleteBasicChatConversationCn", - "tags": ["会话管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamCn" } ], + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string" + } + } + ], "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { - "type": "object", "required": ["user"], - "properties": { "user": { "type": "string", "description": "用户标识。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。" } } + "type": "object", + "properties": { + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "请求示例" + } } } } }, - "responses": { "204": { "description": "会话删除成功，无内容返回。" } } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "会话重命名", - "description": "对会话进行重命名。", - "operationId": "renameBasicChatConversationCn", - "tags": ["会话管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamCn" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequestCn" } } } - }, "responses": { - "200": { "description": "会话重命名成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameResponseCn" } } } } - } - } - }, - "/conversations/{conversation_id}/variables": { - "get": { - "summary": "获取对话变量", - "description": "从特定对话中检索变量。此端点对于提取对话过程中捕获的结构化数据非常有用。", - "operationId": "getBasicChatConversationVariablesCn", - "tags": ["会话管理"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParamCn" }, - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { "$ref": "#/components/parameters/LastIdQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" }, - { "$ref": "#/components/parameters/VariableNameQueryParamCn" } - ], - "responses": { - "200": { "description": "成功获取对话变量。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariablesResponseCn" } } } }, - "404": { "$ref": "#/components/responses/ConversationNotFoundCn" } + "204": { + "description": "会话删除成功。" + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会话不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } } } }, "/audio-to-text": { "post": { "summary": "语音转文字", - "description": "将语音文件转换为文字。支持格式：mp3, mp4, mpeg, mpga, m4a, wav, webm。文件大小限制：15MB。", + "description": "将音频文件转换为文字。支持的格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件大小限制为 `30 MB`。", "operationId": "basicChatAudioToTextCn", - "tags": ["语音与文字转换"], + "tags": [ + "语音与文字转换" + ], "requestBody": { "required": true, - "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequestCn" } } } + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } }, "responses": { - "200": { "description": "成功将语音转换为文字。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponseCn" } } } } + "200": { + "description": "语音转文字成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "响应示例", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `no_audio_uploaded` : 未上传音频文件。\n- `provider_not_support_speech_to_text` : 模型提供商不支持语音转文字。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 语音识别请求失败。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音频文件大小超出限制。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 不允许的音频类型。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } } } }, "/text-to-audio": { "post": { "summary": "文字转语音", - "description": "将文字内容转换为语音。", + "description": "将文字转换为语音。", "operationId": "basicChatTextToAudioCn", - "tags": ["语音与文字转换"], + "tags": [ + "语音与文字转换" + ], "requestBody": { "required": true, - "content": { - "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TextToAudioFormRequestCn" } } + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "请求示例", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } } }, "responses": { "200": { - "description": "成功生成语音文件。", - "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, - "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } + "description": "返回生成的音频文件。`Content-Type` 头设置为音频 MIME 类型（例如 `audio/wav`、`audio/mp3`）。如果 `streaming` 为 `true`，音频将以分块传输编码方式流式返回。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 文字转语音请求失败。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } } } } @@ -561,250 +1862,2565 @@ "/info": { "get": { "summary": "获取应用基本信息", + "description": "获取应用的基本信息，包括名称、描述、标签和模式。", "operationId": "getBasicChatAppInfoCn", - "tags": ["应用配置"], - "responses": { "200": { "description": "应用基本信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "responses": { + "200": { + "description": "应用的基本信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "响应示例", + "value": { + "name": "My Chat App", + "description": "一个有用的客服聊天机器人。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "chat", + "author_name": "Dify Team" + } + } + } + } + } + } + } } }, "/parameters": { "get": { "summary": "获取应用参数", - "description": "用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。", + "description": "获取应用的输入表单配置，包括功能开关、输入参数名称、类型和默认值。", "operationId": "getBasicChatAppParametersCn", - "tags": ["应用配置"], - "responses": { "200": { "description": "应用参数信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAppParametersResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "responses": { + "200": { + "description": "应用参数信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "响应示例", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : 应用不可用或配置错误。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } } }, "/meta": { "get": { - "summary": "获取应用Meta信息", - "description": "用于获取工具 icon。", + "summary": "获取应用元数据", + "description": "获取应用的元数据，包括工具图标和其他配置详情。", "operationId": "getBasicChatAppMetaCn", - "tags": ["应用配置"], - "responses": { "200": { "description": "成功获取应用 Meta 信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "responses": { + "200": { + "description": "成功获取应用元数据。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "响应示例", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } } }, "/site": { "get": { "summary": "获取应用 WebApp 设置", - "description": "用于获取应用的 WebApp 设置。", + "description": "获取应用的 WebApp 设置，包括站点配置、主题和自定义选项。", "operationId": "getBasicChatWebAppSettingsCn", - "tags": ["应用配置"], - "responses": { "200": { "description": "WebApp 设置信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "responses": { + "200": { + "description": "应用的 WebApp 设置。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "响应示例", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "一个有用的客服聊天机器人。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 未找到此应用的站点或工作空间已归档。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } + } + }, + "/apps/annotations": { + "post": { + "summary": "创建标注", + "description": "创建新的标注。标注提供预定义的问答对，应用可以直接匹配并返回，而无需生成回复。", + "operationId": "createChatAnnotationZh", + "tags": [ + "标注管理" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAnnotationRequest" + }, + "examples": { + "createAnnotation": { + "summary": "请求示例", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "标注创建成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "createdAnnotation": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 0, + "created_at": 1705407629 + } + } + } + } + } + } + } + }, + "get": { + "summary": "获取标注列表", + "description": "获取应用的标注分页列表。支持关键词搜索筛选。", + "operationId": "listChatAnnotationsZh", + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "分页页码。", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页条目数。", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "keyword", + "in": "query", + "description": "按问题或回答内容筛选标注的关键词。", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "成功获取标注列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationListResponse" + }, + "examples": { + "annotationList": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 5, + "created_at": 1705407629 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + } + } + } + }, + "/apps/annotations/{annotation_id}": { + "put": { + "summary": "更新标注", + "description": "更新现有标注的问题和回答。", + "operationId": "updateChatAnnotationZh", + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "要更新的标注的唯一标识符。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateAnnotationRequest" + }, + "examples": { + "updateAnnotation": { + "summary": "请求示例", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "标注更新成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "updatedAnnotation": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", + "hit_count": 5, + "created_at": 1705407629 + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 编辑标注的权限不足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 标注不存在。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } + } + }, + "delete": { + "summary": "删除标注", + "description": "删除标注及其关联的命中历史。", + "operationId": "deleteChatAnnotationZh", + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "要删除的标注的唯一标识符。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "标注删除成功。" + }, + "403": { + "description": "`forbidden` : 编辑标注的权限不足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 标注不存在。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } + } + } + }, + "/apps/annotation-reply/{action}": { + "post": { + "summary": "配置标注回复", + "description": "启用或禁用标注回复功能。启用时需要配置嵌入模型。异步执行——使用 [查询标注回复配置任务状态](/api-reference/标注管理/查询标注回复配置任务状态) 跟踪进度。", + "operationId": "setChatAnnotationReplyZh", + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "要执行的操作。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" + }, + "examples": { + "enableAnnotationReply": { + "summary": "请求示例", + "value": { + "score_threshold": 0.9, + "embedding_provider_name": "openai", + "embedding_model_name": "text-embedding-3-small" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "标注回复设置任务已启动。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" + }, + "examples": { + "annotationReplyResponse": { + "summary": "响应示例", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "waiting" + } + } + } + } + } + } + } + } + }, + "/apps/annotation-reply/{action}/status/{job_id}": { + "get": { + "summary": "查询标注回复配置任务状态", + "description": "获取由 [配置标注回复](/api-reference/标注管理/配置标注回复) 发起的异步标注回复配置任务的状态。", + "operationId": "getChatAnnotationReplyStatusZh", + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "操作类型，必须与 [配置标注回复](/api-reference/标注管理/配置标注回复) 调用中的一致。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "由 [配置标注回复](/api-reference/标注管理/配置标注回复) 接口返回的任务 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "成功获取任务状态。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "响应示例", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 指定的任务不存在。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "The job does not exist." + } + } + } + } + } + } + } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key 鉴权。所有 API 请求都应在 Authorization HTTP Header 中包含你的 API-Key，格式为：Bearer {API_KEY}。强烈建议开发者把 API-Key 放在后端存储，而非客户端，以免泄露。" } - }, - "parameters": { - "PageQueryParamCn": { "name": "page", "in": "query", "description": "页码，（选填）默认值：1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamCn": { "name": "limit", "in": "query", "description": "每页数量，（选填）默认值：20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Cn": { "name": "limit", "in": "query", "description": "一次请求返回多少条记录，默认 20 条。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100Cn": { "name": "limit", "in": "query", "description": "一次请求返回多少条记录，默认 20 条，最大 100 条，最小 1 条。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParamCn": { "name": "user", "in": "query", "required": true, "description": "用户标识，由开发者定义规则，需保证用户标识在应用内唯一。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。", "schema": { "type": "string" } }, - "ConversationIdQueryParamCn": { "name": "conversation_id", "in": "query", "required": true, "description": "会话 ID。", "schema": { "type": "string", "format": "uuid" } }, - "LastIdQueryParamCn": { "name": "last_id", "in": "query", "description": "（选填）当前页最后面一条记录的 ID，默认 null。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, - "SortByQueryParamCn": { "name": "sort_by", "in": "query", "description": "（选填）排序字段，默认 -updated_at (按更新时间倒序排列)。可选值：created_at, -created_at, updated_at, -updated_at。'-' 代表倒序。", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParamCn": { "name": "conversation_id", "in": "path", "required": true, "description": "会话 ID。", "schema": { "type": "string", "format": "uuid" } }, - "VariableNameQueryParamCn": { "name": "variable_name", "in": "query", "description": "（选填）按变量名称筛选。", "schema": { "type": "string" } } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**" + } }, "responses": { - "BadRequestGenericCn": { "description": "请求参数错误。可能原因：invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "BadRequestFileCn": { "description": "文件操作请求错误。可能原因：no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "FileTooLargeCn": { "description": "文件太大 (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "UnsupportedFileTypeFileCn": { "description": "不支持的文件类型 (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "S3ErrorFileCn": { "description": "S3 存储服务错误。可能原因：s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "InternalServerErrorCn": { "description": "服务内部异常。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "SuccessResultCn": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFoundCn": { "description": "对话不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "EndUserNotFoundCn": { "description": "终端用户不存在。错误码：`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } } + "SuccessResult": { + "description": "操作成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "结果状态。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "BasicChatRequestCn": { + "ChatRequest": { "type": "object", - "required": ["query", "user"], + "required": [ + "inputs", + "query", + "user" + ], "properties": { - "query": { "type": "string", "description": "用户输入/提问内容。" }, + "query": { + "type": "string", + "description": "用户输入/问题内容。" + }, "inputs": { "type": "object", - "description": "允许传入 App 定义的各变量值。", - "additionalProperties": true, - "default": {} + "description": "允许输入应用定义的各种变量值。包含键值对。请参阅 [获取应用参数](/api-reference/应用配置/获取应用参数) 响应中的 `user_input_form` 字段，以了解应用所需的变量名称和类型。", + "additionalProperties": true }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "响应模式。streaming (推荐) 基于 SSE；blocking 等待执行完毕后返回 (Cloudflare 100秒超时限制；Agent模式下不允许)。" }, - "user": { "type": "string", "description": "用户标识，应用内唯一。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "（选填）会话 ID，用于继续之前的对话。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/BasicInputFileObjectCn" }, "description": "（选填）上传的文件列表 (目前仅支持图片)。" }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "（选填）自动生成会话标题，默认 true。" } - } - }, - "BasicInputFileObjectCn": { - "type": "object", - "required": ["type", "transfer_method"], - "properties": { - "type": { "type": "string", "enum": ["image"], "description": "文件类型，目前仅支持 'image'。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "传递方式，remote_url 用于图片 URL / local_file 用于文件上传" }, - "url": { "type": "string", "format": "url", "description": "图片地址（当传递方式为 remote_url 时）" }, - "upload_file_id": { "type": "string", "format":"uuid", "description": "上传文件 ID，必须通过事先上传文件接口获得（当传递方式为 local_file 时）" } - }, - "anyOf": [ - { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "响应返回模式。`streaming`（推荐）使用 SSE。`blocking` 在完成后返回（长时间处理可能中断；Agent 助手模式不支持此选项）。Cloudflare 超时时间为 `100 s`。未指定时默认为阻塞模式。" }, - { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format":"uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "user": { + "type": "string", + "description": "用户标识符，在应用内唯一。此标识符用于限定数据访问范围——会话、消息和文件仅在使用相同的 `user` 值查询时可见。" + }, + "conversation_id": { + "type": "string", + "description": "用于继续会话的会话 ID。传入上一条消息的 `conversation_id`。要开始新会话，请省略此字段或传入空字符串。响应会返回一个 `conversation_id`——在后续消息中传入该值即可继续该会话。" + }, + "files": { + "type": "array", + "description": "用于多模态理解的文件列表，包括图片、文档、音频和视频。要附加本地文件，请先通过 [上传文件](/api-reference/文件操作/上传文件) 上传，然后将返回的 `id` 作为 `upload_file_id`，并设置 `transfer_method: local_file`。", + "items": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "文件类型。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件 URL（当 `transfer_method` 为 `remote_url` 时必填）。" + }, + "upload_file_id": { + "type": "string", + "description": "通过 [上传文件](/api-reference/文件操作/上传文件) API 获取的已上传文件 ID（当 `transfer_method` 为 `local_file` 时必填）。" + } + } + } + }, + "auto_generate_name": { + "type": "boolean", + "description": "自动生成会话标题。如果为 `false`，请使用 [重命名会话](/api-reference/会话管理/重命名会话) API 并设置 `auto_generate: true` 来异步生成标题。", + "default": true } - ] + } }, - "ChatCompletionResponseCn": { - "type": "object", "description": "阻塞模式下的完整 App 结果。", + "ChatCompletionResponse": { + "type": "object", "properties": { - "event": { "type": "string", "example": "message", "description": "事件类型，固定为 `message`。" }, - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, - "id": { "type": "string", "format": "uuid", "description": "唯一ID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯一 ID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, - "mode": { "type": "string", "example": "chat", "description": "App 模式，固定为 `chat`。" }, - "answer": { "type": "string", "description": "完整回复内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataCn" }, - "created_at": { "type": "integer", "format": "int64", "description": "消息创建时间戳。" } - } - }, - "ResponseMetadataCn": { - "type": "object", "description": "元数据。", - "properties": { "usage": { "$ref": "#/components/schemas/UsageCn" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceCn" }, "description": "引用和归属分段列表。" } } - }, - "ChunkBasicChatEventCn": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "agent_message", "agent_thought", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], "description": "事件类型。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "message": "#/components/schemas/StreamEventChatMessageCn", - "agent_message": "#/components/schemas/StreamEventAgentMessageCn", - "agent_thought": "#/components/schemas/StreamEventAgentThoughtCn", - "message_file": "#/components/schemas/StreamEventMessageFileCn", - "message_end": "#/components/schemas/StreamEventMessageEndCn", - "tts_message": "#/components/schemas/StreamEventTtsMessageCn", - "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndCn", - "message_replace": "#/components/schemas/StreamEventMessageReplaceCn", - "error": "#/components/schemas/StreamEventErrorCn", - "ping": "#/components/schemas/StreamEventPingCn" - }} - }, - "StreamEventBaseChatCn": { - "type": "object", "properties": { - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯一 ID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, - "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" } - } - }, - "StreamEventChatMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLM 返回文本块内容。" } } } ] }, - "StreamEventAgentMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "Agent模式下 LLM 返回文本块内容。" } } } ] }, - "StreamEventAgentThoughtCn": { - "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, - { "type": "object", "required": ["id", "position"], + "event": { + "type": "string", + "description": "事件类型，固定为 `message`。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "用于请求追踪和停止响应 API 的任务 ID。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "该响应事件的唯一 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯一的消息 ID。调用反馈或推荐问题接口时，将此值作为 `message_id` 参数使用。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "mode": { + "type": "string", + "description": "应用模式，固定为 `chat`。" + }, + "answer": { + "type": "string", + "description": "完整的响应内容。" + }, + "metadata": { + "type": "object", + "description": "包含用量和检索资源的元数据。", "properties": { - "id": { "type": "string", "format": "uuid", "description": "agent_thought ID。" }, - "position": { "type": "integer", "description": "agent_thought 在消息中的位置。" }, - "thought": { "type": "string", "description": "agent 的思考内容。" }, - "observation": { "type": "string", "description": "工具调用的返回结果。" }, - "tool": { "type": "string", "description": "使用的工具列表，以 ';' 分割。" }, - "tool_input": { "type": "string", "description": "工具的输入，JSON 格式的字符串。" }, - "message_files": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "当前 agent_thought 关联的文件ID列表 (原描述为 file_id 字符串，修正为数组以匹配 agent_thoughts 历史消息中的 files)。" } + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用的检索资源列表。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "消息创建时间戳（Unix 纪元秒）。" + } + } + }, + "ChunkChatEvent": { + "type": "object", + "description": "流式模式下 Server-Sent Event 块的基础 schema。", + "properties": { + "event": { + "type": "string", + "description": "事件类型。", + "enum": [ + "message", + "agent_message", + "tts_message", + "tts_message_end", + "agent_thought", + "message_file", + "message_end", + "message_replace", + "error", + "ping" + ] + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventChatMessage", + "agent_message": "#/components/schemas/StreamEventChatAgentMessage", + "tts_message": "#/components/schemas/StreamEventChatTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", + "agent_thought": "#/components/schemas/StreamEventChatAgentThought", + "message_file": "#/components/schemas/StreamEventChatMessageFile", + "message_end": "#/components/schemas/StreamEventChatMessageEnd", + "message_replace": "#/components/schemas/StreamEventChatMessageReplace", + "error": "#/components/schemas/StreamEventChatError", + "ping": "#/components/schemas/StreamEventChatPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "description": "流式事件的基础属性。", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "任务 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯一消息 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + } + } + }, + "StreamEventChatMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "answer": { + "type": "string", + "description": "LLM 返回的文本块。" + } } } ] }, - "StreamEventMessageFileCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { "id": { "type": "string", "format": "uuid", "description": "文件唯一ID。" }, "type": { "type": "string", "enum": ["image"], "description": "文件类型，目前仅为 image。" }, "belongs_to": { "type": "string", "enum": ["assistant"], "description": "文件归属，仅为 assistant。" }, "url": { "type": "string", "format": "url", "description": "文件访问地址。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会话ID。" } } } ] }, - "StreamEventMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataCn" } } } ] }, - "StreamEventTtsMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 编码的音频块。" } } } ] }, - "StreamEventTtsMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空字符串。" } } } ] }, - "StreamEventMessageReplaceCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "替换内容（直接替换 LLM 所有回复文本）。" } } } ] }, - "StreamEventErrorCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "type": "object", "required": ["task_id", "status", "code", "message"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "消息唯一 ID（错误事件中可能不存在）。" }, "status": { "type": "integer", "description": "HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } ] }, - "StreamEventPingCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "type": "object", "description": "每 10s 一次的 ping 事件，保持连接存活。" } ] }, - "UsageCn": { "type": "object", "description": "模型用量信息。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceCn": { "type": "object", "description": "引用和归属分段信息。", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } }, - "FileUploadResponseCn": { "type": "object", "description": "文件上传成功后的响应。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件大小 (byte)。" }, "extension": { "type": "string", "description": "文件后缀。" }, "mime_type": { "type": "string", "description": "文件 mime-type。" }, "created_by": { "type": "string", "format": "uuid", "description": "上传人 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "上传时间。" } } }, - "EndUserDetailCn": { + "StreamEventChatAgentMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "answer": { + "type": "string", + "description": "LLM 返回的文本块（Agent 模式）。" + } + } + } + ] + }, + "StreamEventChatTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流事件（base64 编码的 Mp3）。自动播放启用时可用。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。" + } + } + } + ] + }, + "StreamEventChatTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流结束事件。", + "properties": { + "audio": { + "type": "string", + "description": "空字符串。标识音频流结束。" + } + } + } + ] + }, + "StreamEventChatAgentThought": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Agent 思考、LLM 推理、工具调用详情（Agent 模式）。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Agent 思考 ID。" + }, + "position": { + "type": "integer", + "description": "该思考在消息序列中的位置。" + }, + "thought": { + "type": "string", + "description": "LLM 正在思考的内容。" + }, + "observation": { + "type": "string", + "description": "工具调用的响应。" + }, + "tool": { + "type": "string", + "description": "调用的工具列表，以 `;` 分隔。" + }, + "tool_input": { + "type": "string", + "description": "工具输入（JSON 格式）。" + }, + "message_files": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "description": "与该思考相关的文件 ID 列表。" + } + } + } + ] + }, + "StreamEventChatMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "消息文件事件，由工具创建的新文件。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "文件唯一 ID。" + }, + "type": { + "type": "string", + "description": "文件类型，例如 `image`。" + }, + "belongs_to": { + "type": "string", + "description": "该文件的所属者。工具生成的文件始终为 `assistant`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件的远程 URL。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + } + } + } + ] + }, + "StreamEventChatMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息结束事件，流式传输已结束。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "消息的唯一 ID。" + }, + "metadata": { + "type": "object", + "description": "包含用量和检索资源的元数据。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用的检索资源列表。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } + ] + }, + "StreamEventChatMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息内容替换事件（例如由于内容审核）。", + "properties": { + "answer": { + "type": "string", + "description": "替换内容。" + }, + "reason": { + "type": "string", + "description": "内容替换的原因。" + } + } + } + ] + }, + "StreamEventChatError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "流式输出过程中的错误事件。", + "properties": { + "status": { + "type": "integer", + "description": "HTTP 状态码。" + }, + "code": { + "type": "string", + "description": "错误码。" + }, + "message": { + "type": "string", + "description": "错误信息。" + } + } + } + ] + }, + "StreamEventChatPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "Ping 事件，用于保持连接活跃。" + } + ] + }, + "Usage": { + "type": "object", + "description": "模型使用信息。", + "properties": { + "prompt_tokens": { + "type": "integer", + "description": "提示词中的令牌数。" + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "每个提示词令牌的单价。" + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "提示词令牌的价格单位。" + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "提示词令牌的总价。" + }, + "completion_tokens": { + "type": "integer", + "description": "补全内容中的令牌数。" + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "每个补全令牌的单价。" + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "补全令牌的价格单位。" + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "补全令牌的总价。" + }, + "total_tokens": { + "type": "integer", + "description": "使用的令牌总数。" + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "所有令牌的总价。" + }, + "currency": { + "type": "string", + "description": "计价货币。" + }, + "latency": { + "type": "number", + "format": "double", + "description": "延迟时间（秒）。" + } + } + }, + "RetrieverResource": { + "type": "object", + "description": "检索资源的引用和归属信息。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "检索资源的唯一 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "该资源所属消息的 ID。" + }, + "position": { + "type": "integer", + "description": "资源在列表中的位置。" + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "知识库 ID。" + }, + "dataset_name": { + "type": "string", + "description": "知识库名称。" + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "文档 ID。" + }, + "document_name": { + "type": "string", + "description": "文档名称。" + }, + "data_source_type": { + "type": "string", + "description": "数据源类型。" + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "文档中特定块的 ID。" + }, + "score": { + "type": "number", + "format": "float", + "description": "资源的相关性评分。" + }, + "hit_count": { + "type": "integer", + "description": "该块被命中的次数。" + }, + "word_count": { + "type": "integer", + "description": "块的字数。" + }, + "segment_position": { + "type": "integer", + "description": "块在文档中的位置。" + }, + "index_node_hash": { + "type": "string", + "description": "索引节点的哈希值。" + }, + "content": { + "type": "string", + "description": "资源的内容片段。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "块内容的摘要。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳（Unix 纪元秒）。" + } + } + }, + "FileUploadResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "唯一文件 ID。" + }, + "name": { + "type": "string", + "description": "文件名。" + }, + "size": { + "type": "integer", + "description": "文件大小（字节）。" + }, + "extension": { + "type": "string", + "nullable": true, + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "文件的 MIME 类型。" + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "上传文件的用户 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "上传时间戳（Unix 纪元秒）。" + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "文件的预览 URL。" + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "文件的源 URL。" + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "文件的原始 URL。" + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的用户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的租户 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的会话 ID。" + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "文件的存储键。" + } } }, - "MessageFeedbackRequestCn": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "点赞 'like', 点踩 'dislike', 撤销点赞 null。" }, "user": { "type": "string", "description": "用户标识。" }, "content": { "type": "string", "nullable": true, "description": "消息反馈的具体信息。" } } }, - "AppFeedbacksResponseCn": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemCn" }, "description": "返回该APP的点赞、反馈列表。" } } }, - "FeedbackItemCn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "SuggestedQuestionsResponseCn": { "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "description": "建议问题列表。" } } }, - "BasicConversationHistoryResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返回条数。" }, "has_more": { "type": "boolean", "description": "是否存在下一页。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BasicConversationMessageItemCn" }, "description": "消息列表。" } } }, - "BasicConversationMessageItemCn": { "type": "object", "description": "会话中的单条消息。", "properties": { "id": { "type": "string", "format": "uuid", "description": "消息 ID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "用户输入参数。" }, "query": { "type": "string", "description": "用户输入/提问内容。" }, "answer": { "type": "string", "description": "回答消息内容。" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItemCn" }, "description": "消息文件列表。" }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"], "description": "点赞 'like' / 点踩 'dislike'。" } }, "description": "反馈信息。" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceCn" }, "description": "引用和归属分段列表。" }, "agent_thoughts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentThoughtItemCn" }, "description": "Agent思考内容（仅Agent模式下不为空）。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间。" } } }, - "MessageFileItemCn": { "type": "object", "description": "消息中的文件项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "文件类型，例如 'image'。" }, "url": { "type": "string", "format": "url", "description": "预览图片地址。" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "文件归属方。" } } }, - "AgentThoughtItemCn": { - "type": "object", "description": "Agent思考内容。", + "EndUserDetail": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "agent_thought ID。" }, - "chain_id": { "type": "string", "format": "uuid", "nullable": true, "description": "（示例中存在，描述中未明确，暂定为可选）"}, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯一ID。" }, - "position": { "type": "integer", "description": "agent_thought在消息中的位置。" }, - "thought": { "type": "string", "description": "agent的思考内容。" }, - "tool": { "type": "string", "description": "使用的工具列表，以 ';' 分割。" }, - "tool_input": { "type": "string", "description": "工具的输入，JSON格式的字符串。" }, - "observation": { "type": "string", "description": "工具调用的返回结果。" }, - "files": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "当前agent_thought关联的文件ID (示例中为files，markdown中为message_files.file_id)。" }, - "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" } + "id": { + "type": "string", + "format": "uuid", + "description": "终端用户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "租户 ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "应用 ID。" + }, + "type": { + "type": "string", + "description": "终端用户类型。Service API 用户固定为 `service_api`。" + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "API 请求中提供的 `user` 标识符（例如 [发送对话消息](/api-reference/对话消息/发送对话消息) 中的 `user` 字段）。" + }, + "name": { + "type": "string", + "nullable": true, + "description": "终端用户名称。" + }, + "is_anonymous": { + "type": "boolean", + "description": "用户是否为匿名用户。当原始 API 请求中未提供 `user` 标识符时，值为 `true`。" + }, + "session_id": { + "type": "string", + "description": "会话标识符。默认为 `external_user_id` 的值。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最后更新时间戳。" + } } }, - "ConversationsListResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返回条数。" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItemCn" }, "description": "会话列表。" } } }, - "ConversationListItemCn": { "type": "object", "description": "会话列表中的单项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, "name": { "type": "string", "description": "会话名称。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "用户输入参数。" }, "status": { "type": "string", "description": "会话状态。" }, "introduction": { "type": "string", "nullable": true, "description": "开场白。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间。" }, "updated_at": { "type": "integer", "format": "int64", "description": "更新时间。" } } }, - "ConversationRenameRequestCn": { "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true, "description": "（选填）名称，若 auto_generate 为 true 时可不传。" }, "auto_generate": { "type": "boolean", "default": false, "description": "（选填）自动生成标题，默认 false。" }, "user": { "type": "string", "description": "用户标识。" } } }, - "ConversationRenameResponseCn": { "$ref": "#/components/schemas/ConversationListItemCn" }, - "ConversationVariablesResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "每页项目数。" }, "has_more": { "type": "boolean", "description": "是否有更多项目。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItemCn" }, "description": "变量列表。" } } }, - "ConversationVariableItemCn": { "type": "object", "description": "对话中的变量项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "变量ID。" }, "name": { "type": "string", "description": "变量名称。" }, "value_type": { "type": "string", "description": "变量类型 (string, number, boolean 等)。" }, "value": { "type": "string", "description": "变量值。" }, "description": { "type": "string", "nullable": true, "description": "变量描述。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最后更新时间戳。" } } }, - "AudioToTextRequestCn": { "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "语音文件。支持格式：['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']。大小限制：15MB。" }, "user": { "type": "string", "description": "用户标识。" } } }, - "AudioToTextResponseCn": { "type": "object", "properties": { "text": { "type": "string", "description": "输出文字。" } } }, - "TextToAudioFormRequestCn": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "消息ID (优先)。" }, "text": { "type": "string", "description": "语音生成内容。" }, "user": { "type": "string", "description": "用户标识。" } }, "description": "需要 `user`。提供 `message_id` 或 `text`。" }, - "AppInfoResponseCn": { "type": "object", "description": "应用基本信息。", "properties": { "name": { "type": "string", "description": "应用名称。" }, "description": { "type": "string", "description": "应用描述。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "应用标签。" } } }, - "ChatAppParametersResponseCn": { "type": "object", "description": "应用参数信息。", "properties": { "opening_statement": { "type": "string", "description": "开场白。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "开场推荐问题列表。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" } }, "description": "启用回答后给出推荐问题。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" } }, "description": "语音转文本。" }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" }, "voice": { "type": "string", "description": "语音类型。" }, "language": { "type": "string", "description": "语言。" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"], "description": "自动播放：enabled 开启, disabled 关闭。" } }, "description": "文本转语音。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" } }, "description": "引用和归属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" } }, "description": "标记回复。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemCn" }, "description": "用户输入表单配置。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "图片设置。支持 png, jpg, jpeg, webp, gif。" } }, "description": "文件上传配置。" }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer", "description": "文档上传大小限制 (MB)。" }, "image_file_size_limit": { "type": "integer", "description": "图片文件上传大小限制（MB）。" }, "audio_file_size_limit": { "type": "integer", "description": "音频文件上传大小限制 (MB)。" }, "video_file_size_limit": { "type": "integer", "description": "视频文件上传大小限制 (MB)。" } }, "description": "系统参数。" } } }, - "UserInputFormItemCn": { "type": "object", "description": "用户输入表单中的控件项。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperCn" }, { "$ref": "#/components/schemas/ParagraphControlWrapperCn" }, { "$ref": "#/components/schemas/SelectControlWrapperCn" } ] }, - "TextInputControlWrapperCn": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlCn" } }, "required":["text-input"] }, - "ParagraphControlWrapperCn": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlCn" } }, "required":["paragraph"] }, - "SelectControlWrapperCn": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlCn" } }, "required":["select"] }, - "TextInputControlCn": { "type": "object", "description": "文本输入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "nullable": true, "description": "默认值。" } } }, - "ParagraphControlCn": { "type": "object", "description": "段落文本输入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "nullable": true, "description": "默认值。" } } }, - "SelectControlCn": { "type": "object", "description": "下拉控件。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "nullable": true, "description": "默认值。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "选项值。" } } }, - "AppMetaResponseCn": { "type": "object", "description": "应用 Meta 信息。", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url", "description": "图标 URL。" }, { "$ref": "#/components/schemas/ToolIconDetailCn" } ] }, "description": "工具图标，键为工具名称。" } } }, - "ToolIconDetailCn": { "type": "object", "description": "工具图标详情。", "properties": { "background": { "type": "string", "description": "hex 格式的背景色。" }, "content": { "type": "string", "description": "emoji。" } } }, - "WebAppSettingsResponseCn": { "type": "object", "description": "应用 WebApp 设置。", "properties": { "title": { "type": "string", "description": "WebApp 名称。" }, "chat_color_theme": { "type": "string", "description": "聊天颜色主题, hex 格式。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "聊天颜色主题是否反转。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "图标类型。" }, "icon": { "type": "string", "description": "图标内容 (emoji 或图片 URL)。" }, "icon_background": { "type": "string", "description": "hex 格式的背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "图标 URL。" }, "description": { "type": "string", "description": "描述。" }, "copyright": { "type": "string", "description": "版权信息。" }, "privacy_policy": { "type": "string", "description": "隐私政策链接。" }, "custom_disclaimer": { "type": "string", "description": "自定义免责声明。" }, "default_language": { "type": "string", "description": "默认语言。" }, "show_workflow_steps": { "type": "boolean", "description": "是否显示工作流详情。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "是否使用 WebApp 图标替换聊天中的机器人图标。" } } }, - "ErrorResponseCn": { "type": "object", "description": "错误响应。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTP 状态码。" }, "code": { "type": "string", "nullable": true, "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } + "MessageFeedbackRequest": { + "type": "object", + "description": "提交消息反馈的请求体。", + "required": [ + "user" + ], + "properties": { + "rating": { + "type": "string", + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "反馈评分。设为 `null` 可撤销之前提交的反馈。" + }, + "user": { + "type": "string", + "description": "用户标识符，由开发者定义，必须确保在应用内唯一。" + }, + "content": { + "type": "string", + "description": "提供额外详情的可选文字反馈。" + } + } + }, + "AppFeedbacksResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "反馈项列表。", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } + } + } + }, + "FeedbackItem": { + "type": "object", + "description": "单条反馈项。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "反馈 ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "应用 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。" + }, + "rating": { + "type": "string", + "description": "反馈评分。`like` 为正面，`dislike` 为负面。" + }, + "content": { + "type": "string", + "nullable": true, + "description": "可选的文字反馈。" + }, + "from_source": { + "type": "string", + "description": "反馈来源。`user` 为终端用户通过 API 提交的反馈，`admin` 为从控制台提交的反馈。" + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "提交反馈的终端用户 ID。当 `from_source` 为 `user` 时存在。" + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "提交反馈的账户 ID。当 `from_source` 为 `admin` 时存在。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最后更新时间戳。" + } + } + }, + "SuggestedQuestionsResponse": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "结果状态。" + }, + "data": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议问题列表。" + } + } + }, + "ConversationHistoryResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "has_more": { + "type": "boolean", + "description": "是否有更多消息。" + }, + "data": { + "type": "array", + "description": "消息列表。", + "items": { + "$ref": "#/components/schemas/ConversationMessageItem" + } + } + } + }, + "ConversationMessageItem": { + "type": "object", + "description": "会话中的单条消息。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "parent_message_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "线程会话的父消息 ID。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "该消息的输入变量。" + }, + "query": { + "type": "string", + "description": "用户查询文本。" + }, + "answer": { + "type": "string", + "description": "助手回答文本。" + }, + "status": { + "type": "string", + "description": "消息状态。成功消息为 `normal`，生成失败时为 `error`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "当 `status` 为 `error` 时的错误消息。" + }, + "message_files": { + "type": "array", + "description": "附加到该消息的文件。", + "items": { + "$ref": "#/components/schemas/MessageFileItem" + } + }, + "feedback": { + "type": "object", + "nullable": true, + "description": "该消息的用户反馈。", + "properties": { + "rating": { + "type": "string", + "description": "反馈评分。`like` 为正面，`dislike` 为负面。" + } + } + }, + "retriever_resources": { + "type": "array", + "description": "该消息使用的检索资源。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + }, + "agent_thoughts": { + "type": "array", + "description": "该消息的 Agent 思考。", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳（Unix 纪元秒）。" + }, + "extra_contents": { + "type": "array", + "description": "与该消息关联的附加执行内容，例如人工介入表单数据。", + "items": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "MessageFileItem": { + "type": "object", + "description": "附加到消息的文件。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "原始文件名。" + }, + "type": { + "type": "string", + "description": "文件类型，例如 `image`。" + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "文件的预览 URL。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "文件的 MIME 类型。" + }, + "size": { + "type": "integer", + "nullable": true, + "description": "文件大小（字节）。" + }, + "transfer_method": { + "type": "string", + "description": "使用的传输方式。`remote_url` 表示基于 URL 的文件，`local_file` 表示已上传的文件，`tool_file` 表示工具生成的文件。" + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "该文件的所属者。用户上传的文件为 `user`，助手生成的文件为 `assistant`。" + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "通过 `local_file` 传输时的上传文件 ID。" + } + } + }, + "AgentThoughtItem": { + "type": "object", + "description": "消息中的 Agent 思考步骤。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Agent 思考 ID。" + }, + "chain_id": { + "type": "string", + "nullable": true, + "description": "该思考的链 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "该思考所属的唯一消息 ID。" + }, + "position": { + "type": "integer", + "description": "该思考的位置。" + }, + "thought": { + "type": "string", + "description": "LLM 正在思考的内容。" + }, + "tool": { + "type": "string", + "description": "调用的工具，以 `;` 分隔。" + }, + "tool_labels": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "已使用工具的标签。" + }, + "tool_input": { + "type": "string", + "description": "工具输入（JSON 格式）。" + }, + "observation": { + "type": "string", + "description": "工具调用的响应。" + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "与该思考相关的文件 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + } + } + }, + "ConversationsListResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "has_more": { + "type": "boolean", + "description": "是否有更多会话。" + }, + "data": { + "type": "array", + "description": "会话列表。", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } + } + } + }, + "ConversationListItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "name": { + "type": "string", + "description": "会话名称。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "会话的输入变量。" + }, + "status": { + "type": "string", + "description": "会话状态。活跃会话为 `normal`。" + }, + "introduction": { + "type": "string", + "description": "会话介绍。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最后更新时间戳。" + } + } + }, + "ConversationRenameRequest": { + "type": "object", + "description": "重命名会话的请求体。", + "properties": { + "name": { + "type": "string", + "description": "会话名称。当 `auto_generate` 为 `false` 时必填。" + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "自动生成会话名称。当为 `true` 时，`name` 字段将被忽略。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "ConversationVariablesResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "has_more": { + "type": "boolean", + "description": "是否有下一页。" + }, + "data": { + "type": "array", + "description": "会话变量列表。", + "items": { + "$ref": "#/components/schemas/ConversationVariableItem" + } + } + } + }, + "ConversationVariableItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Variable ID." + }, + "name": { + "type": "string", + "description": "变量名称。" + }, + "value_type": { + "type": "string", + "description": "变量值类型。可选值：`string`、`number`、`object`、`secret`、`file`、`boolean`、`array[any]`、`array[string]`、`array[number]`、`array[object]`、`array[file]`、`array[boolean]`。" + }, + "value": { + "type": "string", + "description": "变量值（复杂类型可以是 JSON 字符串）。" + }, + "description": { + "type": "string", + "description": "变量描述。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最后更新时间戳。" + } + } + }, + "ConversationVariableUpdateRequest": { + "type": "object", + "description": "更新会话变量的请求体。", + "required": [ + "value" + ], + "properties": { + "value": { + "description": "变量的新值。必须与变量的预期类型匹配。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "语音转文字的请求体。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音频文件。支持格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。大小限制：`30 MB`。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "语音识别输出的文字。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "文字转语音的请求体。提供 `message_id` 或 `text` 其中之一。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。当同时提供 `text` 时，优先使用消息 ID。" + }, + "text": { + "type": "string", + "description": "要转换的语音内容。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + }, + "voice": { + "type": "string", + "description": "文字转语音使用的声音。可用声音取决于为此应用配置的 TTS 提供商。使用[获取应用参数](/api-reference/应用配置/获取应用参数) → `text_to_speech.voice` 中的 `voice` 值作为默认值。" + }, + "streaming": { + "type": "boolean", + "description": "是否启用流式响应。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "应用名称。" + }, + "description": { + "type": "string", + "description": "应用描述。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "应用标签。" + }, + "mode": { + "type": "string", + "description": "应用模式。`chat` 表示基础聊天应用，`agent-chat` 表示 Agent 应用，`advanced-chat` 表示对话流应用。" + }, + "author_name": { + "type": "string", + "description": "应用作者名称。" + } + } + }, + "ChatAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "会话开始时显示的开场白。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议的初始问题列表。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答后建议问题的配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "语音转文字配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "文字转语音配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + }, + "voice": { + "type": "string", + "description": "TTS 的声音标识符。" + }, + "language": { + "type": "string", + "description": "TTS 的语言。" + }, + "autoPlay": { + "type": "string", + "description": "自动播放设置。`enabled` 为自动播放音频，`disabled` 为需要手动播放。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "检索资源配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "标注回复配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "更多类似内容配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "敏感词过滤配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "user_input_form": { + "type": "array", + "description": "用户输入表单元素列表。", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "文件上传配置。", + "properties": { + "image": { + "type": "object", + "description": "图片上传设置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用图片上传。" + }, + "number_limits": { + "type": "integer", + "description": "最大图片数量。" + }, + "detail": { + "type": "string", + "description": "图片精细程度。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "允许的传输方式。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "系统级参数和限制。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "最大文件大小（MB）。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最大图片文件大小（MB）。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最大音频文件大小（MB）。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最大视频文件大小（MB）。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "工作流文件上传的最大文件数。" + } + } + } + } + }, + "UserInputFormItem": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } + ] + }, + "TextInputControlWrapper": { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } + }, + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } + }, + "SelectControlWrapper": { + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } + }, + "TextInputControl": { + "type": "object", + "description": "文本输入表单控件。", + "properties": { + "label": { + "type": "string", + "description": "显示标签。" + }, + "variable": { + "type": "string", + "description": "变量名称。" + }, + "required": { + "type": "boolean", + "description": "输入是否必填。" + }, + "default": { + "type": "string", + "description": "默认值。" + } + } + }, + "ParagraphControl": { + "type": "object", + "description": "段落（多行文本）表单控件。", + "properties": { + "label": { + "type": "string", + "description": "显示标签。" + }, + "variable": { + "type": "string", + "description": "变量名称。" + }, + "required": { + "type": "boolean", + "description": "输入是否必填。" + }, + "default": { + "type": "string", + "description": "默认值。" + } + } + }, + "SelectControl": { + "type": "object", + "description": "下拉选择表单控件。", + "properties": { + "label": { + "type": "string", + "description": "显示标签。" + }, + "variable": { + "type": "string", + "description": "变量名称。" + }, + "required": { + "type": "boolean", + "description": "是否必须选择。" + }, + "default": { + "type": "string", + "description": "默认选中的值。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "此表单控件的可选值列表。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "图标的 URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "工具图标。键为工具名称。" + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "使用 emoji 的工具图标详情。", + "properties": { + "background": { + "type": "string", + "description": "十六进制格式的背景颜色。" + }, + "content": { + "type": "string", + "description": "Emoji 内容。" + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp 标题。" + }, + "chat_color_theme": { + "type": "string", + "description": "聊天主题颜色。" + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "聊天主题颜色是否反转。" + }, + "icon_type": { + "type": "string", + "description": "使用的图标类型。`emoji` 为表情图标，`image` 为上传的图片图标。" + }, + "icon": { + "type": "string", + "description": "图标内容（表情或图片 ID）。" + }, + "icon_background": { + "type": "string", + "description": "图标背景颜色。" + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "图标图片的 URL。" + }, + "description": { + "type": "string", + "description": "WebApp 描述。" + }, + "copyright": { + "type": "string", + "description": "版权文本。" + }, + "privacy_policy": { + "type": "string", + "description": "隐私政策 URL。" + }, + "custom_disclaimer": { + "type": "string", + "description": "自定义免责声明文本。" + }, + "default_language": { + "type": "string", + "description": "默认语言代码。" + }, + "show_workflow_steps": { + "type": "boolean", + "description": "是否显示工作流步骤。" + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "是否使用应用图标作为回答图标。" + } + } + }, + "AnnotationListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "description": "当前页面的标注项列表。" + }, + "has_more": { + "type": "boolean", + "description": "如果当前结果集之后还有更多页面，则为 `true`。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "匹配查询条件的标注总数。" + }, + "page": { + "type": "integer", + "description": "当前页码。" + } + } + }, + "AnnotationItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "标注唯一标识符。" + }, + "question": { + "type": "string", + "nullable": true, + "description": "触发该标注的问题文本。" + }, + "answer": { + "type": "string", + "nullable": true, + "description": "标注被匹配时返回的预定义回答。" + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "该标注被匹配并作为回复返回的次数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "创建时间戳（Unix 纪元秒）。" + } + } + }, + "CreateAnnotationRequest": { + "type": "object", + "description": "创建新标注的请求体。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "标注问题。" + }, + "answer": { + "type": "string", + "description": "标注答案。" + } + } + }, + "UpdateAnnotationRequest": { + "type": "object", + "description": "更新标注的请求体。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "更新后的标注问题。" + }, + "answer": { + "type": "string", + "description": "更新后的标注答案。" + } + } + }, + "InitialAnnotationReplySettingsRequest": { + "type": "object", + "description": "配置标注回复设置的请求体。", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], + "properties": { + "embedding_provider_name": { + "type": "string", + "description": "嵌入模型提供商名称（例如 `openai`、`cohere`）。" + }, + "embedding_model_name": { + "type": "string", + "description": "用于标注匹配的嵌入模型名称（例如 `text-embedding-3-small`）。" + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "标注被视为匹配的最低相似度分数。值越高，要求匹配越精确。", + "minimum": 0, + "maximum": 1 + } + } + }, + "InitialAnnotationReplySettingsResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "异步任务 ID。配合 [查询标注回复配置任务状态](/api-reference/标注管理/查询标注回复配置任务状态) 使用以跟踪进度。" + }, + "job_status": { + "type": "string", + "description": "当前任务状态。`waiting` 表示排队中，`processing` 表示处理中，`completed` 表示已完成，`error` 表示失败。" + } + } + }, + "InitialAnnotationReplySettingsStatusResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "来自 [配置标注回复](/api-reference/标注管理/配置标注回复) 调用的任务 ID。" + }, + "job_status": { + "type": "string", + "description": "当前任务状态。`waiting` 表示排队中，`processing` 表示处理中，`completed` 表示已完成，`error` 表示失败。" + }, + "error_msg": { + "type": "string", + "description": "描述任务失败原因的错误消息。当 `job_status` 不是 `error` 时为空字符串。" + } + } + } } }, "tags": [ - { "name": "对话消息", "description": "与对话消息和交互相关的操作。" }, - { "name": "文件操作", "description": "文件上传和预览相关的操作。" }, - { "name": "终端用户", "description": "终端用户信息相关的操作。" }, - { "name": "消息反馈", "description": "用户对消息的反馈操作。" }, - { "name": "会话管理", "description": "管理对话会话相关的操作。" }, - { "name": "语音与文字转换", "description": "文本转语音和语音转文本操作。" }, - { "name": "应用配置", "description": "获取应用设置和信息相关的操作。" } + { + "name": "对话消息", + "description": "与聊天消息和交互相关的操作。" + }, + { + "name": "文件操作", + "description": "文件上传和预览操作。" + }, + { + "name": "终端用户", + "description": "终端用户信息相关操作。" + }, + { + "name": "消息反馈", + "description": "用户反馈操作。" + }, + { + "name": "会话管理", + "description": "与管理会话相关的操作。" + }, + { + "name": "语音与文字转换", + "description": "文字转语音和语音转文字操作。" + }, + { + "name": "应用配置", + "description": "获取应用设置和信息的操作。" + }, + { + "name": "标注管理", + "description": "与管理标注直接回复相关的操作。" + } ] -} \ No newline at end of file +} diff --git a/zh/api-reference/openapi_chatflow.json b/zh/api-reference/openapi_chatflow.json index 34128013..35bd2155 100644 --- a/zh/api-reference/openapi_chatflow.json +++ b/zh/api-reference/openapi_chatflow.json @@ -1,18 +1,18 @@ { "openapi": "3.0.1", "info": { - "title": "工作流编排对话型应用 API (Chatflow API)", - "description": "对话应用支持会话持久化，可将之前的聊天记录作为上下文进行回答，可适用于聊天/客服 AI 等。", + "title": "工作流编排对话型应用 API (对话流 API)", + "description": "对话流应用支持会话持久化，允许将之前的聊天记录作为响应的上下文。对话流应用使用 `advanced-chat` 模式，提供工作流级别的流式事件，用于详细的执行追踪，包括节点开始、完成、迭代和工作流生命周期。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API 的基础 URL。请将 {api_base_url} 替换为你的应用提供的实际 API 基础 URL。", + "description": "工作流编排对话型应用 API 的基础 URL。请将 {api_base_url} 替换为你的应用实际提供的 API 基础 URL。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "实际的 API 基础 URL" + "description": "API 的实际基础 URL" } } } @@ -26,27 +26,29 @@ "/chat-messages": { "post": { "summary": "发送对话消息", - "description": "创建会话消息。", + "description": "向对话型应用发送请求。", "operationId": "sendChatMessageCn", - "tags": ["对话消息"], + "tags": [ + "对话消息" + ], "requestBody": { "description": "发送对话消息的请求体。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatRequestCn" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file": { - "summary": "包含文件和自定义输入的流式请求示例", + "streaming_example": { + "summary": "请求示例 - 流式模式", "value": { "inputs": { - "name": "dify" + "city": "San Francisco" }, - "query": "iPhone 13 Pro Max 的规格是什么？", + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "conversation_id": "", "user": "abc-123", "files": [ { @@ -56,57 +58,15 @@ } ] } - } - } - } - } - }, - "responses": { - "200": { - "description": "请求成功。响应的内容类型和结构取决于请求中的 `response_mode` 参数。\n- 当 `response_mode` 为 `blocking` 时，返回 `application/json` 格式的 `ChatCompletionResponseCn` 对象。\n- 当 `response_mode` 为 `streaming` 时，返回 `text/event-stream` 格式的 `ChunkChatEventCn` 对象流式序列。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChatCompletionResponseCn" - } - }, - "text/event-stream": { - "schema": { - "type": "string", - "description": "SSE 事件流。每个事件以 'data: ' 开头，以 '\\n\\n' 结尾。具体结构请参见 `ChunkChatEventCn`。" - } - } - } - }, - "400": { "$ref": "#/components/responses/BadRequestGenericCn" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } - } - } - }, - "/files/upload": { - "post": { - "summary": "上传文件", - "description": "上传文件并在发送消息时使用，可实现图文多模态理解。支持你的应用程序所支持的所有格式。上传的文件仅供当前终端用户使用。", - "operationId": "uploadFileCn", - "tags": ["文件操作"], - "requestBody": { - "description": "文件上传请求。需使用 `multipart/form-data` 进行请求。", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "要上传的文件。" - }, - "user": { - "type": "string", - "description": "用户标识，必须和发送消息接口传入 user 保持一致。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。" + }, + "blocking_example": { + "summary": "请求示例 - 阻塞模式", + "value": { + "inputs": {}, + "query": "What are the specs of the iPhone 13 Pro Max?", + "response_mode": "blocking", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "user": "abc-123" } } } @@ -115,183 +75,219 @@ }, "responses": { "200": { - "description": "文件上传成功。", + "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `ChatCompletionResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkChatEvent` 对象流。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/FileUploadResponseCn" + "$ref": "#/components/schemas/ChatCompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "响应示例 - 阻塞模式", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "advanced-chat", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + } } - } - } - }, - "201": { - "description": "文件创建成功 (备选成功状态码)。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseCn" } } } - }, - "400": { "$ref": "#/components/responses/BadRequestFileCn" }, - "413": { "$ref": "#/components/responses/FileTooLargeCn" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileCn" }, - "503": { "$ref": "#/components/responses/S3ErrorFileCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "获取终端用户", - "description": "通过 ID 获取终端用户信息。\n\n当其他 API 返回终端用户 ID（例如文件上传接口返回的 `created_by`）时，可使用该接口查询对应的终端用户信息。", - "operationId": "getEndUserChatflowCn", - "tags": ["终端用户"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "终端用户 ID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "responses": { - "200": { - "description": "成功获取终端用户信息。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailCn" } - } - } - }, - "404": { "$ref": "#/components/responses/EndUserNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } - } - } - }, - "/files/{file_id}/preview": { - "get": { - "summary": "文件预览", - "description": "预览或下载已上传的文件。此端点允许你访问之前通过文件上传API上传的文件。文件只能在所属的应用程序消息内访问。", - "operationId": "previewChatFlowFileCn", - "tags": ["文件操作"], - "parameters": [ - { - "name": "file_id", - "in": "path", - "required": true, - "description": "要预览的文件的唯一标识符，从文件上传API响应中获取。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "as_attachment", - "in": "query", - "required": false, - "description": "是否强制作为附件下载文件。默认为`false`（在浏览器中预览）。", - "schema": { - "type": "boolean", - "default": false - } - } - ], - "responses": { - "200": { - "description": "文件内容成功返回。根据文件类型和请求参数设置响应头。", - "content": { - "image/png": { + }, + "text/event-stream": { "schema": { "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - }, - "headers": { - "Content-Type": { - "description": "文件的MIME类型", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "文件大小（字节）（如果可用）", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "如果as_attachment=true，则设置为'attachment'", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "用于性能的缓存头", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "对于音频/视频文件设置为'bytes'", - "schema": { - "type": "string", - "example": "bytes" + "description": "服务器发送事件 (SSE) 流。每个事件是一个以 `data: ` 为前缀的 JSON 对象，以两个换行符终止。\n\n**SSE 解析指南：**每个事件是一行以 `data: ` 为前缀的 JSON 对象，以 `\\n\\n` 终止。解析 JSON 前先去除 `data: ` 前缀。JSON 内的 `event` 字段决定事件类型。当收到终止事件（如 `message_end`、`workflow_finished` 或 `error`）时流结束。忽略 `ping` 事件（每 10 秒发送一次以保持连接活跃）。注意即使流中出现错误事件，HTTP 状态码仍为 `200`。" + }, + "examples": { + "streamingResponseBasic": { + "summary": "Response Example - Streaming (Basic)", + "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" + }, + "streamingResponseWorkflow": { + "summary": "Response Example - Streaming (工作流)", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}" + } } } } }, "400": { - "description": "错误请求。可能的错误代码:\n- `invalid_param`: 异常参数输入。", + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 文本生成失败。\n- `bad_request` : Cannot use draft 工作流 version.\n- `bad_request` : Invalid `workflow_id` format.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } - } - } - }, - "403": { - "description": "禁止访问。可能的错误代码:\n- `file_access_denied`: 文件访问被拒绝或文件不属于当前应用程序。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "conversation_completed": { + "summary": "conversation_completed", + "value": { + "status": 400, + "code": "conversation_completed", + "message": "The conversation has ended. Please start a new conversation." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "is_draft_workflow": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. " + } + }, + "workflow_id_format_error": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Invalid workflow_id format: 'not-a-valid-id'. " + } + } + } } } }, "404": { - "description": "未找到。可能的错误代码:\n- `file_not_found`: 文件未找到或已被删除。", + "description": "- `not_found` : Conversation does not exist.\n- `not_found` : 工作流 not found with the specified `workflow_id`.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "workflow_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab" + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 上游模型提供商的速率限制已超出。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } } } }, "500": { - "description": "内部服务器错误。", + "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -301,16 +297,20 @@ "/chat-messages/{task_id}/stop": { "post": { "summary": "停止响应", - "description": "停止生成对话消息。仅支持流式模式。", + "description": "停止聊天消息生成任务。仅在 `streaming` 模式下支持。", "operationId": "stopChatMessageGenerationCn", - "tags": ["对话消息"], + "tags": [ + "对话消息" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "任务 ID，可在流式返回 Chunk 中获取。", - "schema": { "type": "string", "format": "uuid" } + "description": "任务 ID，可以从 [发送对话消息](/api-reference/对话消息/发送对话消息) API 的流式分块返回中获取。", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -319,66 +319,45 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { "user": { "type": "string", - "description": "用户标识，必须和发送消息接口传入 user 保持一致。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。" + "description": "用户标识符，必须和发送消息接口传入的 user 保持一致。" + } + } + }, + "examples": { + "example": { + "summary": "请求示例", + "value": { + "user": "abc-123" } } } } } }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "消息反馈（点赞）", - "description": "消息终端用户反馈、点赞，方便应用开发者优化输出预期。", - "operationId": "postMessageFeedbackCn", - "tags": ["消息反馈"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestCn" } - } - } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } - } - } - }, - "/app/feedbacks": { - "get": { - "summary": "获取APP的消息点赞和反馈", - "description": "获取应用的终端用户反馈、点赞。", - "operationId": "getAppFeedbacksCn", - "tags": ["消息反馈"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamCn" } - ], "responses": { "200": { - "description": "成功获取应用的反馈列表。", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseCn" } + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } } } } @@ -388,54 +367,547 @@ "/messages/{message_id}/suggested": { "get": { "summary": "获取下一轮建议问题列表", - "description": "获取当前消息的下一轮建议问题列表。", + "description": "获取当前消息的下一步建议问题。", "operationId": "getSuggestedQuestionsCn", - "tags": ["对话消息"], + "tags": [ + "对话消息" + ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string" + } }, - { "$ref": "#/components/parameters/UserQueryParamCn" } + { + "name": "user", + "in": "query", + "required": true, + "description": "用户标识符。", + "schema": { + "type": "string" + } + } ], "responses": { "200": { - "description": "成功获取建议问题列表。", + "description": "成功获取建议问题。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponseCn" } + "schema": { + "$ref": "#/components/schemas/SuggestedQuestionsResponse" + }, + "examples": { + "suggestedQuestions": { + "summary": "响应示例", + "value": { + "result": "success", + "data": [ + "What colors does the iPhone 13 Pro Max come in?", + "How does the battery compare to iPhone 12?", + "What is the price range?" + ] + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `bad_request` : 建议问题功能已禁用。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Suggested Questions Is Disabled." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 消息不存在。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } } } }, - "/messages": { - "get": { - "summary": "获取会话历史消息", - "description": "滚动加载形式返回历史聊天记录，第一页返回最新 `limit` 条，即倒序返回。", - "operationId": "getConversationHistoryCn", - "tags": ["会话管理"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdQueryParamCn" }, - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { - "name": "first_id", - "in": "query", - "description": "当前页第一条聊天记录的 ID，默认 null。", - "schema": { "type": "string", "format": "uuid", "nullable": true } + "/files/upload": { + "post": { + "operationId": "uploadFileCn", + "tags": [ + "文件操作" + ], + "summary": "上传文件", + "description": "上传文件用于发送消息时使用，支持图片、文档、音频和视频的多模态理解。上传的文件仅供当前终端用户使用。", + "requestBody": { + "description": "文件上传请求。需要 multipart/form-data 格式。", + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "要上传的文件。支持的类型包括图片、文档、音频和视频。" + }, + "user": { + "type": "string", + "description": "用户标识符，由开发者定义的规则生成，必须在应用内唯一。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "文件上传成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Cn" } + "400": { + "description": "- `no_file_uploaded` : 请求中未提供文件。\n- `too_many_files` : 每次请求仅允许上传一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : 文件大小超出限制。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 不允许的文件类型。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { + "get": { + "operationId": "previewChatFlowFileCn", + "tags": [ + "文件操作" + ], + "summary": "下载文件", + "description": "预览或下载之前通过[上传文件](/api-reference/文件操作/上传文件) API 上传的文件。仅可访问属于请求应用内消息的文件。", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "要预览的文件唯一标识符，从 [上传文件](/api-reference/文件操作/上传文件) API 响应中获取。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "如果为 `true`，则强制文件以附件形式下载，而不是在浏览器中预览。", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符，用于终端用户上下文。", + "schema": { + "type": "string" + } + } ], "responses": { "200": { - "description": "成功获取会话历史消息。", + "description": "返回原始文件内容。`Content-Type` 头设置为文件的 MIME 类型。如果 `as_attachment` 为 `true`，文件将以 `Content-Disposition: attachment` 方式作为下载返回。", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : 拒绝访问请求的文件。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationHistoryResponseCn" } + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : 未找到请求的文件。", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "operationId": "getEndUserChatflowCn", + "tags": [ + "终端用户" + ], + "summary": "获取终端用户信息", + "description": "根据 ID 获取终端用户信息。当其他 API 返回终端用户 ID（例如[上传文件](/api-reference/文件操作/上传文件)返回的 `created_by`）时很有用。", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "终端用户 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "成功获取终端用户。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "响应示例", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : 未找到终端用户。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/messages/{message_id}/feedbacks": { + "post": { + "operationId": "postMessageFeedbackCn", + "tags": [ + "消息反馈" + ], + "summary": "提交消息反馈", + "description": "提交消息反馈。终端用户可以对消息评价 `like` 或 `dislike`，并可选择提供文字反馈。将 `rating` 设为 `null` 可撤销之前提交的反馈。", + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "消息 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "请求示例", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : 消息不存在。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/app/feedbacks": { + "get": { + "operationId": "getAppFeedbacksCn", + "tags": [ + "消息反馈" + ], + "summary": "获取应用的消息反馈", + "description": "获取此应用中所有消息反馈的分页列表，包括终端用户和管理员反馈。", + "parameters": [ + { + "name": "page", + "in": "query", + "description": "分页页码。", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页记录数。", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } + } + ], + "responses": { + "200": { + "description": "应用反馈列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "rating": "like", + "content": "The response accurately answered my question about product specifications.", + "from_source": "user", + "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "from_account_id": null, + "created_at": "2025-01-16T14:30:29Z", + "updated_at": "2025-01-16T14:30:29Z" + }, + { + "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", + "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", + "rating": "dislike", + "content": "The answer was too vague and did not address the specific pricing question.", + "from_source": "user", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", + "from_account_id": null, + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" + } + ] + } + } + } } } } @@ -445,21 +917,615 @@ "/conversations": { "get": { "summary": "获取会话列表", - "description": "获取当前用户的会话列表，默认返回最近的 20 条。", + "description": "获取当前用户的会话列表，按最近活跃时间排序。", "operationId": "getConversationsListCn", - "tags": ["会话管理"], + "tags": [ + "会话管理" + ], "parameters": [ - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { "$ref": "#/components/parameters/LastIdQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" }, - { "$ref": "#/components/parameters/SortByQueryParamCn" } + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符。", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "当前页最后一条记录的 ID（用于分页）。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "返回的记录数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "sort_by", + "in": "query", + "required": false, + "description": "排序字段。使用 '-' 前缀表示降序。", + "schema": { + "type": "string", + "enum": [ + "created_at", + "-created_at", + "updated_at", + "-updated_at" + ], + "default": "-updated_at" + } + } ], "responses": { "200": { "description": "成功获取会话列表。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationsListResponseCn" } + "schema": { + "$ref": "#/components/schemas/ConversationsListResponse" + }, + "examples": { + "conversationsList": { + "summary": "响应示例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 上一个会话不存在（无效的 `last_id`）。", + "content": { + "application/json": { + "examples": { + "last_conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Last Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/messages": { + "get": { + "summary": "获取会话历史消息", + "description": "以滚动加载的格式返回历史聊天记录，首页返回最新的 `limit` 条消息，即按时间倒序排列。", + "operationId": "getConversationHistoryCn", + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符。", + "schema": { + "type": "string" + } + }, + { + "name": "first_id", + "in": "query", + "required": false, + "description": "当前页第一条聊天记录的 ID。默认为 `null`（获取最新消息）。获取后续页面时，使用当前列表中第一条消息的 ID 来获取更早的消息。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "每次请求返回的聊天历史消息数量。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "成功获取会话历史。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "响应示例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "parent_message_id": null, + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "status": "normal", + "error": null, + "message_files": [], + "feedback": { + "rating": "like" + }, + "retriever_resources": [], + "agent_thoughts": [], + "created_at": 1705407629 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 会话不存在。\n- `not_found` : 第一条消息不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "first_message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "First Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables": { + "get": { + "summary": "获取对话变量", + "description": "从特定会话中获取变量。", + "operationId": "getConversationVariablesCn", + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符。", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "当前页最后一条记录的 ID（用于分页）。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "返回的记录数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "variable_name", + "in": "query", + "required": false, + "description": "按指定名称筛选变量。", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + } + ], + "responses": { + "200": { + "description": "成功获取会话变量。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariablesResponse" + }, + "examples": { + "conversationVariables": { + "summary": "响应示例", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "dark_mode", + "description": "用户偏好设置", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会话不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/name": { + "post": { + "summary": "重命名会话", + "description": "重命名会话或自动生成名称。会话名称用于在支持多会话的客户端上显示。", + "operationId": "renameConversationCn", + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationRenameRequest" + }, + "examples": { + "renameExample": { + "summary": "请求示例", + "value": { + "name": "iPhone Specs Chat", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "会话重命名成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationListItem" + }, + "examples": { + "renamedConversation": { + "summary": "响应示例", + "value": { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会话不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables/{variable_id}": { + "put": { + "summary": "更新对话变量", + "description": "更新特定会话变量的值。值必须与预期类型匹配。", + "operationId": "updateChatflowConversationVariableZh", + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "variable_id", + "in": "path", + "required": true, + "description": "Variable ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableUpdateRequest" + }, + "examples": { + "updateStringVariable": { + "summary": "请求示例", + "value": { + "value": "new value", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "变量更新成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableItem" + }, + "examples": { + "updatedVariable": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "new value", + "description": "用户偏好设置", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `bad_request` : 变量值类型不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "type_mismatch": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Value type mismatch: expected string, got integer." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 会话不存在。\n- `not_found` : 会话变量不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "variable_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Variable Not Exists." + } + } + } } } } @@ -469,384 +1535,4673 @@ "/conversations/{conversation_id}": { "delete": { "summary": "删除会话", - "description": "删除一个指定的会话。", + "description": "删除会话。", "operationId": "deleteConversationCn", - "tags": ["会话管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamCn" } ], + "tags": [ + "会话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "会话 ID。", + "schema": { + "type": "string" + } + } + ], "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { - "type": "object", "required": ["user"], - "properties": { "user": { "type": "string", "description": "用户标识。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。" } } + "type": "object", + "properties": { + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "请求示例" + } } } } }, - "responses": { "204": { "description": "会话删除成功，无内容返回。" } } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "会话重命名", - "description": "对会话进行重命名。", - "operationId": "renameConversationCn", - "tags": ["会话管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamCn" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequestCn" } } } - }, "responses": { - "200": { "description": "会话重命名成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameResponseCn" } } } } - } - } - }, - "/conversations/{conversation_id}/variables": { - "get": { - "summary": "获取对话变量", - "description": "从特定对话中检索变量。此端点对于提取对话过程中捕获的结构化数据非常有用。", - "operationId": "getConversationVariablesCn", - "tags": ["会话管理"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParamCn" }, - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { "$ref": "#/components/parameters/LastIdQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" } - ], - "responses": { - "200": { "description": "成功获取对话变量。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariablesResponseCn" } } } }, - "404": { "$ref": "#/components/responses/ConversationNotFoundCn" } + "204": { + "description": "会话删除成功。无返回内容。" + }, + "400": { + "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 会话不存在。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } } } }, "/audio-to-text": { "post": { - "summary": "语音转文字", - "description": "将语音文件转换为文字。支持格式：mp3, mp4, mpeg, mpga, m4a, wav, webm。文件大小限制：15MB。", "operationId": "audioToTextCn", - "tags": ["语音与文字转换"], + "tags": [ + "语音与文字转换" + ], + "summary": "语音转文字", + "description": "将音频文件转换为文字。支持的格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件大小限制为 `30 MB`。", "requestBody": { "required": true, - "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequestCn" } } } + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } }, "responses": { - "200": { "description": "成功将语音转换为文字。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponseCn" } } } } + "200": { + "description": "语音转文字成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "响应示例", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `no_audio_uploaded` : 未上传音频文件。\n- `provider_not_support_speech_to_text` : 模型提供商不支持语音转文字。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 语音识别请求失败。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音频文件大小超出限制。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 不允许的音频类型。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } } } }, "/text-to-audio": { "post": { - "summary": "文字转语音", - "description": "将文字内容转换为语音。", "operationId": "textToAudioCn", - "tags": ["语音与文字转换"], + "tags": [ + "语音与文字转换" + ], + "summary": "文字转语音", + "description": "将文字转换为语音。", "requestBody": { "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToAudioJsonRequestCn" } } } + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "请求示例", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } }, "responses": { "200": { - "description": "成功生成语音文件。", - "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, - "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } + "description": "返回生成的音频文件。`Content-Type` 头设置为音频 MIME 类型（例如 `audio/wav`、`audio/mp3`）。如果 `streaming` 为 `true`，音频将以分块传输编码方式流式返回。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 文字转语音请求失败。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } } } } }, "/info": { "get": { - "summary": "获取应用基本信息", "operationId": "getAppInfoCn", - "tags": ["应用配置"], - "responses": { "200": { "description": "应用基本信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "summary": "获取应用基本信息", + "description": "获取应用的基本信息，包括名称、描述、标签和模式。", + "responses": { + "200": { + "description": "应用的基本信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "响应示例", + "value": { + "name": "My Chatflow App", + "description": "一个有用的客服聊天机器人。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "advanced-chat", + "author_name": "Dify Team" + } + } + } + } + } + } + } } }, "/parameters": { "get": { - "summary": "获取应用参数", - "description": "用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。", "operationId": "getAppParametersCn", - "tags": ["应用配置"], - "responses": { "200": { "description": "应用参数信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAppParametersResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "summary": "获取应用参数", + "description": "获取应用的输入表单配置，包括功能开关、输入参数名称、类型和默认值。", + "responses": { + "200": { + "description": "应用参数信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "响应示例", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : 应用不可用或配置错误。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } } }, "/meta": { "get": { - "summary": "获取应用Meta信息", - "description": "用于获取工具 icon。", "operationId": "getAppMetaCn", - "tags": ["应用配置"], - "responses": { "200": { "description": "成功获取应用 Meta 信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "summary": "获取应用元数据", + "description": "获取应用的元数据，包括工具图标和其他配置详情。", + "responses": { + "200": { + "description": "成功获取应用元数据。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "响应示例", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } } }, "/site": { "get": { - "summary": "获取应用 WebApp 设置", - "description": "用于获取应用的 WebApp 设置。", "operationId": "getWebAppSettingsCn", - "tags": ["应用配置"], - "responses": { "200": { "description": "WebApp 设置信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "summary": "获取应用 WebApp 设置", + "description": "获取应用的 WebApp 设置，包括站点配置、主题和自定义选项。", + "responses": { + "200": { + "description": "应用的 WebApp 设置。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "响应示例", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "一个有用的客服聊天机器人。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 未找到此应用的站点或工作空间已归档。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } } }, "/apps/annotations": { - "get": { - "summary": "获取标注列表", - "operationId": "getAnnotationListCn", - "tags": ["标注管理"], - "parameters": [ { "$ref": "#/components/parameters/PageQueryParamCn" }, { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" } ], - "responses": { "200": { "description": "成功获取标注列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationListResponseCn" } } } } } - }, "post": { "summary": "创建标注", + "description": "创建新的标注。标注提供预定义的问答对，应用可以直接匹配并返回，而无需生成回复。", "operationId": "createAnnotationCn", - "tags": ["标注管理"], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationRequestCn" } } } }, + "tags": [ + "标注管理" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAnnotationRequest" + }, + "examples": { + "createAnnotation": { + "summary": "请求示例", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform." + } + } + } + } + } + }, "responses": { - "200": { "description": "标注创建成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItemCn" } } } }, - "201": { "description": "标注创建成功 (备选)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItemCn" } } } } + "201": { + "description": "标注创建成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "createdAnnotation": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 0, + "created_at": 1705407629 + } + } + } + } + } + } + } + }, + "get": { + "summary": "获取标注列表", + "description": "获取应用的标注分页列表。支持关键词搜索筛选。", + "operationId": "getAnnotationListCn", + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "分页页码。", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页条目数。", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "keyword", + "in": "query", + "description": "按问题或回答内容筛选标注的关键词。", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "成功获取标注列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationListResponse" + }, + "examples": { + "annotationList": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform.", + "hit_count": 5, + "created_at": 1705407629 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + } } } }, "/apps/annotations/{annotation_id}": { "put": { "summary": "更新标注", + "description": "更新现有标注的问题和回答。", "operationId": "updateAnnotationCn", - "tags": ["标注管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParamCn" } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequestCn" } } } }, - "responses": { "200": { "description": "标注更新成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItemCn" } } } } } + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "要更新的标注的唯一标识符。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateAnnotationRequest" + }, + "examples": { + "updateAnnotation": { + "summary": "请求示例", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "标注更新成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "updatedAnnotation": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", + "hit_count": 5, + "created_at": 1705407629 + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 编辑标注的权限不足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 标注不存在。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } + } }, "delete": { "summary": "删除标注", + "description": "删除标注及其关联的命中历史。", "operationId": "deleteAnnotationCn", - "tags": ["标注管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParamCn" } ], - "responses": { "204": { "description": "标注删除成功。" } } + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "要删除的标注的唯一标识符。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "标注删除成功。" + }, + "403": { + "description": "`forbidden` : 编辑标注的权限不足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 标注不存在。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } + } } }, "/apps/annotation-reply/{action}": { "post": { - "summary": "标注回复初始设置", - "description": "启用或禁用标注回复功能，并配置相关的嵌入模型和阈值。此接口异步执行。", + "summary": "配置标注回复", + "description": "启用或禁用标注回复功能。启用时需要配置嵌入模型。异步执行——使用 [查询标注回复配置任务状态](/api-reference/标注管理/查询标注回复配置任务状态) 跟踪进度。", "operationId": "initialAnnotationReplySettingsCn", - "tags": ["标注管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationActionPathParamCn" } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequestCn" } } } }, + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "要执行的操作。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" + }, + "examples": { + "enableAnnotationReply": { + "summary": "请求示例", + "value": { + "score_threshold": 0.9, + "embedding_provider_name": "openai", + "embedding_model_name": "text-embedding-3-small" + } + } + } + } + } + }, "responses": { - "200": { "description": "任务已启动。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponseCn" } } } }, - "202": { "description": "任务已接受处理。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponseCn" } } } } + "200": { + "description": "标注回复设置任务已启动。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" + }, + "examples": { + "annotationReplyResponse": { + "summary": "响应示例", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "waiting" + } + } + } + } + } + } } } }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { - "summary": "查询标注回复初始设置任务状态", + "summary": "查询标注回复配置任务状态", + "description": "获取由 [配置标注回复](/api-reference/标注管理/配置标注回复) 发起的异步标注回复配置任务的状态。", "operationId": "getInitialAnnotationReplySettingsStatusCn", - "tags": ["标注管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationActionPathParamCn" }, { "$ref": "#/components/parameters/JobIdPathParamCn" } ], - "responses": { "200": { "description": "任务状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponseCn" } } } } } + "tags": [ + "标注管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "操作类型，必须与 [配置标注回复](/api-reference/标注管理/配置标注回复) 调用中的一致。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "由 [配置标注回复](/api-reference/标注管理/配置标注回复) 接口返回的任务 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "成功获取任务状态。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "响应示例", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 指定的任务不存在。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "The job does not exist." + } + } + } + } + } + } + } + } + }, + "/workflows/run/{workflow_run_id}": { + "get": { + "summary": "获取工作流执行情况", + "description": "根据工作流执行 ID 获取工作流任务的当前执行结果。", + "operationId": "getChatflowWorkflowRunDetailZh", + "tags": [ + "工作流执行" + ], + "parameters": [ + { + "name": "workflow_run_id", + "in": "path", + "required": true, + "description": "工作流运行 ID，可从流式事件或消息元数据中获取。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "成功获取工作流运行详情。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "响应示例", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } + } + } + }, + "400": { + "description": "`not_workflow_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未找到工作流运行记录。", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } + } + } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "获取工作流日志", + "description": "获取分页的工作流执行日志，支持筛选选项。", + "operationId": "listChatflowWorkflowLogsZh", + "tags": [ + "工作流执行" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "在日志中搜索的关键词。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "按执行状态筛选。", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "分页页码。", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页条目数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "筛选在此 ISO 8601 时间戳之前创建的日志。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "筛选在此 ISO 8601 时间戳之后创建的日志。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "按终端用户会话 ID 筛选。", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "按账户 ID 筛选。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "成功获取工作流日志。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "响应示例", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0 + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_chatflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } + } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key 鉴权。所有 API 请求都应在 Authorization HTTP Header 中包含你的 API-Key，格式为：Bearer {API_KEY}。强烈建议开发者把 API-Key 放在后端存储，而非客户端，以免泄露。" } - }, - "parameters": { - "PageQueryParamCn": { "name": "page", "in": "query", "description": "页码，（选填）默认值：1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamCn": { "name": "limit", "in": "query", "description": "每页数量，（选填）默认值：20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Cn": { "name": "limit", "in": "query", "description": "一次请求返回多少条记录，默认 20 条。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100Cn": { "name": "limit", "in": "query", "description": "一次请求返回多少条记录，默认 20 条，最大 100 条，最小 1 条。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParamCn": { "name": "user", "in": "query", "required": true, "description": "用户标识，由开发者定义规则，需保证用户标识在应用内唯一。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。", "schema": { "type": "string" } }, - "ConversationIdQueryParamCn": { "name": "conversation_id", "in": "query", "required": true, "description": "会话 ID。", "schema": { "type": "string", "format": "uuid" } }, - "LastIdQueryParamCn": { "name": "last_id", "in": "query", "description": "（选填）当前页最后面一条记录的 ID，默认 null。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, - "SortByQueryParamCn": { "name": "sort_by", "in": "query", "description": "（选填）排序字段，默认 -updated_at (按更新时间倒序排列)。可选值：created_at, -created_at, updated_at, -updated_at。'-' 代表倒序。", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParamCn": { "name": "conversation_id", "in": "path", "required": true, "description": "会话 ID。", "schema": { "type": "string", "format": "uuid" } }, - "AnnotationIdPathParamCn": { "name": "annotation_id", "in": "path", "required": true, "description": "标注 ID。", "schema": { "type": "string", "format": "uuid" } }, - "AnnotationActionPathParamCn": { "name": "action", "in": "path", "required": true, "description": "动作，只能是 'enable' 或 'disable'。", "schema": { "type": "string", "enum": ["enable", "disable"] } }, - "JobIdPathParamCn": { "name": "job_id", "in": "path", "required": true, "description": "任务 ID，从标注回复初始设置接口返回的 job_id。", "schema": { "type": "string", "format": "uuid" } } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**" + } }, "responses": { - "BadRequestGenericCn": { "description": "请求参数错误。可能原因：invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "BadRequestFileCn": { "description": "文件操作请求错误。可能原因：no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "FileTooLargeCn": { "description": "文件太大 (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "UnsupportedFileTypeFileCn": { "description": "不支持的文件类型 (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "S3ErrorFileCn": { "description": "S3 存储服务错误。可能原因：s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "InternalServerErrorCn": { "description": "服务内部异常。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "SuccessResultCn": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFoundCn": { "description": "对话不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "EndUserNotFoundCn": { "description": "终端用户不存在。错误码：`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } } + "SuccessResult": { + "description": "操作成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "结果状态。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "ChatRequestCn": { + "ChatRequest": { "type": "object", - "required": ["query", "user"], + "required": [ + "inputs", + "query", + "user" + ], "properties": { - "query": { "type": "string", "description": "用户输入/提问内容。" }, + "query": { + "type": "string", + "description": "用户输入/问题内容。" + }, "inputs": { "type": "object", - "description": "允许传入 App 定义的各变量值。如果变量是文件类型，请指定一个 InputFileObjectCn 对象。", - "additionalProperties": { - "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "$ref": "#/components/schemas/InputFileObjectCn" } ] - }, - "default": {} + "description": "允许输入应用定义的各种变量值。包含键值对。请参阅 [获取应用参数](/api-reference/应用配置/获取应用参数) 响应中的 `user_input_form` 字段，以了解应用所需的变量名称和类型。", + "additionalProperties": true }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "响应模式。streaming (推荐) 基于 SSE；blocking 等待执行完毕后返回 (Cloudflare 100秒超时限制)。" }, - "user": { "type": "string", "description": "用户标识，应用内唯一。**重要说明**: Service API 不共享 WebApp 创建的对话。通过 API 创建的对话与 WebApp 界面中创建的对话是相互隔离的。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "（选填）会话 ID，用于继续之前的对话。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectCn" }, "description": "（选填）文件列表，仅当模型支持 Vision 能力时可用。" }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "（选填）自动生成会话标题，默认 true。" } + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "响应返回模式。`streaming`（推荐）使用 SSE。`blocking` 等待完成后返回（长时间处理可能会被中断）。Cloudflare 超时为 `100 s`。省略时默认为阻塞模式。" + }, + "user": { + "type": "string", + "description": "用户标识符，在应用内唯一。此标识符用于限定数据访问范围——会话、消息和文件仅在使用相同的 `user` 值查询时可见。" + }, + "conversation_id": { + "type": "string", + "description": "用于继续会话的会话 ID。传入上一条消息的 `conversation_id`。要开始新会话，请省略此字段或传入空字符串。响应会返回一个 `conversation_id`——在后续消息中传入该值即可继续该会话。" + }, + "files": { + "type": "array", + "description": "用于多模态理解的文件列表，包括图片、文档、音频和视频。要附加本地文件，请先通过 [上传文件](/api-reference/文件操作/上传文件) 上传，然后将返回的 `id` 作为 `upload_file_id`，并设置 `transfer_method: local_file`。", + "items": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "文件类型。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件 URL（当 `transfer_method` 为 `remote_url` 时必填）。" + }, + "upload_file_id": { + "type": "string", + "description": "通过 [上传文件](/api-reference/文件操作/上传文件) API 获取的已上传文件 ID（当 `transfer_method` 为 `local_file` 时必填）。" + } + } + } + }, + "auto_generate_name": { + "type": "boolean", + "description": "自动生成会话标题。如果为 `false`，请使用 [重命名会话](/api-reference/会话管理/重命名会话) API 并设置 `auto_generate: true` 来异步生成标题。", + "default": true + }, + "workflow_id": { + "type": "string", + "description": "指定要执行的已发布工作流版本 ID。如果未提供，将使用最新发布的版本。" + } } }, - "InputFileObjectCn": { + "ChatCompletionResponse": { "type": "object", - "required": ["type", "transfer_method"], "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "文件类型。document: TXT,MD,PDF等; image: JPG,PNG等; audio: MP3,WAV等; video: MP4,MOV等; custom: 其他。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "传递方式，remote_url 用于图片 URL / local_file 用于文件上传" }, - "url": { "type": "string", "format": "url", "description": "图片地址（当传递方式为 remote_url 时）" }, - "upload_file_id": { "type": "string", "format":"uuid", "description": "上传文件 ID，必须通过事先上传文件接口获得（当传递方式为 local_file 时）" } + "event": { + "type": "string", + "description": "事件类型，固定为 `message`。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "用于请求追踪和停止响应 API 的任务 ID。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "该响应事件的唯一 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯一的消息 ID。调用反馈或推荐问题接口时，将此值作为 `message_id` 参数使用。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "mode": { + "type": "string", + "description": "应用模式，固定为 `advanced-chat`。" + }, + "answer": { + "type": "string", + "description": "完整的响应内容。" + }, + "metadata": { + "type": "object", + "description": "包含用量和检索资源的元数据。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用的检索资源列表。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "消息创建时间戳（Unix 纪元秒）。" + } + } + }, + "ChunkChatEvent": { + "type": "object", + "description": "流式模式下 Server-Sent Event 块的基础 schema。", + "properties": { + "event": { + "type": "string", + "description": "事件类型。", + "enum": [ + "message", + "tts_message", + "tts_message_end", + "message_file", + "message_end", + "message_replace", + "workflow_started", + "workflow_finished", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "workflow_paused", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "agent_log", + "text_chunk", + "text_replace", + "error", + "ping" + ] + } }, - "anyOf": [ + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventChatMessage", + "tts_message": "#/components/schemas/StreamEventChatTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", + "message_file": "#/components/schemas/StreamEventChatMessageFile", + "message_end": "#/components/schemas/StreamEventChatMessageEnd", + "message_replace": "#/components/schemas/StreamEventChatMessageReplace", + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "text_chunk": "#/components/schemas/StreamEventChatTextChunk", + "text_replace": "#/components/schemas/StreamEventChatTextReplace", + "error": "#/components/schemas/StreamEventChatError", + "ping": "#/components/schemas/StreamEventChatPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "description": "流式事件的基础属性。", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "任务 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯一消息 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + } + } + }, + "StreamEventChatMessage": { + "allOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "$ref": "#/components/schemas/ChunkChatEvent" }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format":"uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "answer": { + "type": "string", + "description": "LLM 返回的文本块。" + } + } } ] }, - "ChatCompletionResponseCn": { - "type": "object", "description": "阻塞模式下的完整 App 结果。", + "StreamEventChatTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流事件（base64 编码的 Mp3）。自动播放启用时可用。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。" + } + } + } + ] + }, + "StreamEventChatTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流结束事件。", + "properties": { + "audio": { + "type": "string", + "description": "空字符串。标识音频流结束。" + } + } + } + ] + }, + "StreamEventChatMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "消息文件事件，由工具创建的新文件。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "文件唯一 ID。" + }, + "type": { + "type": "string", + "description": "文件类型，例如 `image`。" + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "该文件的归属方，此处始终为 `assistant`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件的远程 URL。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + } + } + } + ] + }, + "StreamEventChatMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息结束事件，流式传输已结束。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "消息的唯一 ID。" + }, + "metadata": { + "type": "object", + "description": "包含用量和检索资源的元数据。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用的检索资源列表。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } + ] + }, + "StreamEventChatMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息内容替换事件（例如由于内容审核）。", + "properties": { + "answer": { + "type": "string", + "description": "替换内容。" + }, + "reason": { + "type": "string", + "description": "内容替换的原因。" + } + } + } + ] + }, + "StreamEventChatError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "流式输出过程中的错误事件。", + "properties": { + "status": { + "type": "integer", + "description": "HTTP 状态码。" + }, + "code": { + "type": "string", + "description": "错误码。" + }, + "message": { + "type": "string", + "description": "错误信息。" + } + } + } + ] + }, + "StreamEventChatPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "Ping 事件，用于保持连接活跃。" + } + ] + }, + "Usage": { + "type": "object", + "description": "模型使用信息。", "properties": { - "event": { "type": "string", "example": "message", "description": "事件类型，固定为 `message`。" }, - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, - "id": { "type": "string", "format": "uuid", "description": "唯一ID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯一 ID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, - "mode": { "type": "string", "example": "chat", "description": "App 模式，固定为 `chat`。" }, - "answer": { "type": "string", "description": "完整回复内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataCn" }, - "created_at": { "type": "integer", "format": "int64", "description": "消息创建时间戳。" } + "prompt_tokens": { + "type": "integer", + "description": "提示词中的令牌数。" + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "每个提示词令牌的单价。" + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "提示词令牌的价格单位。" + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "提示词令牌的总价。" + }, + "completion_tokens": { + "type": "integer", + "description": "补全内容中的令牌数。" + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "每个补全令牌的单价。" + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "补全令牌的价格单位。" + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "补全令牌的总价。" + }, + "total_tokens": { + "type": "integer", + "description": "使用的令牌总数。" + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "所有令牌的总价。" + }, + "currency": { + "type": "string", + "description": "计价货币。" + }, + "latency": { + "type": "number", + "format": "double", + "description": "延迟时间（秒）。" + } } }, - "ResponseMetadataCn": { - "type": "object", "description": "元数据。", - "properties": { "usage": { "$ref": "#/components/schemas/UsageCn" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceCn" }, "description": "引用和归属分段列表。" } } - }, - "ChunkChatEventCn": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "workflow_started", "node_started", "node_finished", "workflow_finished", "error", "ping"], "description": "事件类型。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "message": "#/components/schemas/StreamEventChatMessageCn", "message_file": "#/components/schemas/StreamEventMessageFileCn", - "message_end": "#/components/schemas/StreamEventMessageEndCn", "tts_message": "#/components/schemas/StreamEventTtsMessageCn", - "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndCn", "message_replace": "#/components/schemas/StreamEventMessageReplaceCn", - "workflow_started": "#/components/schemas/StreamEventWorkflowStartedCn", "node_started": "#/components/schemas/StreamEventNodeStartedCn", - "node_finished": "#/components/schemas/StreamEventNodeFinishedCn", "workflow_finished": "#/components/schemas/StreamEventWorkflowFinishedCn", - "error": "#/components/schemas/StreamEventErrorCn", "ping": "#/components/schemas/StreamEventPingCn" - }} - }, - "StreamEventBaseChatCn": { - "type": "object", "properties": { - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯一 ID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, - "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" } + "RetrieverResource": { + "type": "object", + "description": "检索资源的引用和归属信息。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "检索资源的唯一 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "该资源所属消息的 ID。" + }, + "position": { + "type": "integer", + "description": "资源在列表中的位置。" + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "知识库 ID。" + }, + "dataset_name": { + "type": "string", + "description": "知识库名称。" + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "文档 ID。" + }, + "document_name": { + "type": "string", + "description": "文档名称。" + }, + "data_source_type": { + "type": "string", + "description": "数据源类型。" + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "文档中特定块的 ID。" + }, + "score": { + "type": "number", + "format": "float", + "description": "资源的相关性评分。" + }, + "hit_count": { + "type": "integer", + "description": "该块被命中的次数。" + }, + "word_count": { + "type": "integer", + "description": "块的字数。" + }, + "segment_position": { + "type": "integer", + "description": "块在文档中的位置。" + }, + "index_node_hash": { + "type": "string", + "description": "索引节点的哈希值。" + }, + "content": { + "type": "string", + "description": "资源的内容片段。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "块内容的摘要。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳（Unix 纪元秒）。" + } } }, - "StreamEventChatMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLM 返回文本块内容。" } } } ] }, - "StreamEventMessageFileCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { "id": { "type": "string", "format": "uuid", "description": "文件唯一ID。" }, "type": { "type": "string", "enum": ["image"], "description": "文件类型，目前仅为 image。" }, "belongs_to": { "type": "string", "enum": ["assistant"], "description": "文件归属，仅为 assistant。" }, "url": { "type": "string", "format": "url", "description": "文件访问地址。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会话ID。" } } } ] }, - "StreamEventMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataCn" } } } ] }, - "StreamEventTtsMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 编码的音频块。" } } } ] }, - "StreamEventTtsMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空字符串。" } } } ] }, - "StreamEventMessageReplaceCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "替换内容（直接替换 LLM 所有回复文本）。" } } } ] }, - "StreamEventWorkflowStartedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/WorkflowStartedDataCn" } } } ] }, - "WorkflowStartedDataCn": { "type": "object", "required": ["id", "workflow_id", "sequence_number", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "关联 Workflow ID。" }, "sequence_number": { "type": "integer", "description": "自增序号，App 内自增，从 1 开始。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间。" } } }, - "StreamEventNodeStartedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/NodeStartedDataCn" } } } ] }, - "NodeStartedDataCn": { "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID (应为 node 执行 ID，根据上下文修正)。" }, "node_id": { "type": "string", "format": "uuid", "description": "节点 ID。" }, "node_type": { "type": "string", "description": "节点类型。" }, "title": { "type": "string", "description": "节点名称。" }, "index": { "type": "integer", "description": "执行序号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "前置节点 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "节点使用的前置变量内容。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间。" } } }, - "StreamEventNodeFinishedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/NodeFinishedDataCn" } } } ] }, - "NodeFinishedDataCn": { "type": "object", "required": ["id", "node_id", "index", "status", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "node 执行 ID。" }, "node_id": { "type": "string", "format": "uuid", "description": "节点 ID。" }, "index": { "type": "integer", "description": "执行序号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "（可选）前置节点 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点使用的前置变量内容。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "（可选）节点过程数据 (JSON)。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "（可选）输出内容 (JSON)。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, "error": { "type": "string", "nullable": true, "description": "（可选）错误原因。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "（可选）耗时(秒)。" }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadataCn" , "nullable": true, "description":"元数据"}, "created_at": { "type": "integer", "format": "int64", "description": "开始时间。" } } }, - "NodeExecutionMetadataCn": { "type": "object", "description": "节点执行元数据。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "（可选）总使用 tokens。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "（可选）总费用 (使用 float 兼容 decimal)。" }, "currency": { "type": "string", "nullable": true, "example": "USD", "description": "（可选）货币。" } } }, - "StreamEventWorkflowFinishedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/WorkflowFinishedDataCn" } } } ] }, - "WorkflowFinishedDataCn": { "type": "object", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "关联 Workflow ID。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "（可选）输出内容 (JSON)。" }, "error": { "type": "string", "nullable": true, "description": "（可选）错误原因。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "（可选）耗时(秒)。" }, "total_tokens": { "type": "integer", "nullable": true, "description": "（可选）总使用 tokens。" }, "total_steps": { "type": "integer", "default": 0, "description": "总步数，默认 0。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间。" }, "finished_at": { "type": "integer", "format": "int64", "description": "结束时间。" } } }, - "StreamEventErrorCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "status", "code", "message"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "消息唯一 ID（错误事件中可能不存在）。" }, "status": { "type": "integer", "description": "HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } ] }, - "StreamEventPingCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "description": "每 10s 一次的 ping 事件，保持连接存活。" } ] }, - "UsageCn": { "type": "object", "description": "模型用量信息。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceCn": { "type": "object", "description": "引用和归属分段信息。", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } }, - "FileUploadResponseCn": { "type": "object", "description": "文件上传成功后的响应。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件大小 (byte)。" }, "extension": { "type": "string", "description": "文件后缀。" }, "mime_type": { "type": "string", "description": "文件 mime-type。" }, "created_by": { "type": "string", "format": "uuid", "description": "上传人 ID (应为 uuid，示例中为 int，已修正)。" }, "created_at": { "type": "integer", "format": "int64", "description": "上传时间。" } } }, - "EndUserDetailCn": { + "FileUploadResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "唯一文件 ID。" + }, + "name": { + "type": "string", + "description": "文件名。" + }, + "size": { + "type": "integer", + "description": "文件大小（字节）。" + }, + "extension": { + "type": "string", + "nullable": true, + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "文件的 MIME 类型。" + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "上传文件的用户 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "上传时间戳（Unix 纪元秒）。" + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "文件的预览 URL。" + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "文件的源 URL。" + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "文件的原始 URL。" + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的用户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的租户 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的会话 ID。" + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "文件的存储键。" + } } }, - "MessageFeedbackRequestCn": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "点赞 'like', 点踩 'dislike', 撤销点赞 null。" }, "user": { "type": "string", "description": "用户标识。" }, "content": { "type": "string", "nullable": true, "description": "消息反馈的具体信息。" } } }, - "AppFeedbacksResponseCn": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemCn" }, "description": "返回该APP的点赞、反馈列表。" } } }, - "FeedbackItemCn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "SuggestedQuestionsResponseCn": { "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "description": "建议问题列表。" } } }, - "ConversationHistoryResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返回条数。" }, "has_more": { "type": "boolean", "description": "是否存在下一页。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessageItemCn" }, "description": "消息列表。" } } }, - "ConversationMessageItemCn": { "type": "object", "description": "会话中的单条消息。", "properties": { "id": { "type": "string", "format": "uuid", "description": "消息 ID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "用户输入参数。" }, "query": { "type": "string", "description": "用户输入/提问内容。" }, "answer": { "type": "string", "description": "回答消息内容。" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItemCn" }, "description": "消息文件列表。" }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"], "description": "点赞 'like' / 点踩 'dislike'。" } }, "description": "反馈信息。" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceCn" }, "description": "引用和归属分段列表。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间。" } } }, - "MessageFileItemCn": { "type": "object", "description": "消息中的文件项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "文件类型，例如 'image'。" }, "url": { "type": "string", "format": "url", "description": "预览图片地址。" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "文件归属方。" } } }, - "ConversationsListResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返回条数。" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItemCn" }, "description": "会话列表。" } } }, - "ConversationListItemCn": { "type": "object", "description": "会话列表中的单项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, "name": { "type": "string", "description": "会话名称。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "用户输入参数。" }, "status": { "type": "string", "description": "会话状态。" }, "introduction": { "type": "string", "nullable": true, "description": "开场白。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间。" }, "updated_at": { "type": "integer", "format": "int64", "description": "更新时间。" } } }, - "ConversationRenameRequestCn": { "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true, "description": "（选填）名称，若 auto_generate 为 true 时可不传。" }, "auto_generate": { "type": "boolean", "default": false, "description": "（选填）自动生成标题，默认 false。" }, "user": { "type": "string", "description": "用户标识。" } } }, - "ConversationRenameResponseCn": { "$ref": "#/components/schemas/ConversationListItemCn" }, - "ConversationVariablesResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "每页项目数。" }, "has_more": { "type": "boolean", "description": "是否有更多项目。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItemCn" }, "description": "变量列表。" } } }, - "ConversationVariableItemCn": { "type": "object", "description": "对话中的变量项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "变量ID。" }, "name": { "type": "string", "description": "变量名称。" }, "value_type": { "type": "string", "description": "变量类型 (string, number, boolean 等)。" }, "value": { "type": "string", "description": "变量值。" }, "description": { "type": "string", "nullable": true, "description": "变量描述。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最后更新时间戳。" } } }, - "AudioToTextRequestCn": { "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "语音文件。支持格式：['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']。大小限制：15MB。" }, "user": { "type": "string", "description": "用户标识。" } } }, - "AudioToTextResponseCn": { "type": "object", "properties": { "text": { "type": "string", "description": "输出文字。" } } }, - "TextToAudioJsonRequestCn": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "消息ID (优先)。" }, "text": { "type": "string", "description": "语音生成内容。" }, "user": { "type": "string", "description": "用户标识。" } }, "description": "需要 `user`。提供 `message_id` 或 `text`。" }, - "AppInfoResponseCn": { "type": "object", "description": "应用基本信息。", "properties": { "name": { "type": "string", "description": "应用名称。" }, "description": { "type": "string", "description": "应用描述。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "应用标签。" } } }, - "ChatAppParametersResponseCn": { "type": "object", "description": "应用参数信息。", "properties": { "opening_statement": { "type": "string", "description": "开场白。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "开场推荐问题列表。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" } }, "description": "启用回答后给出推荐问题。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" } }, "description": "语音转文本。" }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" }, "voice": { "type": "string", "description": "语音类型。" }, "language": { "type": "string", "description": "语言。" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"], "description": "自动播放：enabled 开启, disabled 关闭。" } }, "description": "文本转语音。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" } }, "description": "引用和归属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" } }, "description": "标记回复。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemCn" }, "description": "用户输入表单配置。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "图片设置。支持 png, jpg, jpeg, webp, gif。" } }, "description": "文件上传配置。" }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer", "description": "文档上传大小限制 (MB)。" }, "image_file_size_limit": { "type": "integer", "description": "图片文件上传大小限制 (MB)。" }, "audio_file_size_limit": { "type": "integer", "description": "音频文件上传大小限制 (MB)。" }, "video_file_size_limit": { "type": "integer", "description": "视频文件上传大小限制 (MB)。" } }, "description": "系统参数。" } } }, - "UserInputFormItemCn": { "type": "object", "description": "用户输入表单中的控件项。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperCn" }, { "$ref": "#/components/schemas/ParagraphControlWrapperCn" }, { "$ref": "#/components/schemas/SelectControlWrapperCn" } ] }, - "TextInputControlWrapperCn": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlCn" } }, "required":["text-input"] }, - "ParagraphControlWrapperCn": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlCn" } }, "required":["paragraph"] }, - "SelectControlWrapperCn": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlCn" } }, "required":["select"] }, - "TextInputControlCn": { "type": "object", "description": "文本输入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "nullable": true, "description": "默认值。" } } }, - "ParagraphControlCn": { "type": "object", "description": "段落文本输入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "nullable": true, "description": "默认值。" } } }, - "SelectControlCn": { "type": "object", "description": "下拉控件。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "nullable": true, "description": "默认值。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "选项值。" } } }, - "AppMetaResponseCn": { "type": "object", "description": "应用 Meta 信息。", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url", "description": "图标 URL。" }, { "$ref": "#/components/schemas/ToolIconDetailCn" } ] }, "description": "工具图标，键为工具名称。" } } }, - "ToolIconDetailCn": { "type": "object", "description": "工具图标详情。", "properties": { "background": { "type": "string", "description": "hex 格式的背景色。" }, "content": { "type": "string", "description": "emoji。" } } }, - "WebAppSettingsResponseCn": { "type": "object", "description": "应用 WebApp 设置。", "properties": { "title": { "type": "string", "description": "WebApp 名称。" }, "chat_color_theme": { "type": "string", "description": "聊天颜色主题, hex 格式。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "聊天颜色主题是否反转。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "图标类型。" }, "icon": { "type": "string", "description": "图标内容 (emoji 或图片 URL)。" }, "icon_background": { "type": "string", "description": "hex 格式的背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "图标 URL。" }, "description": { "type": "string", "description": "描述。" }, "copyright": { "type": "string", "description": "版权信息。" }, "privacy_policy": { "type": "string", "description": "隐私政策链接。" }, "custom_disclaimer": { "type": "string", "description": "自定义免责声明。" }, "default_language": { "type": "string", "description": "默认语言。" }, "show_workflow_steps": { "type": "boolean", "description": "是否显示工作流详情。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "是否使用 WebApp 图标替换聊天中的机器人图标。" } } }, - "AnnotationListResponseCn": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItemCn" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } }, - "AnnotationItemCn": { "type": "object", "description": "标注项。", "properties": { "id": { "type": "string", "format": "uuid" }, "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" }, "hit_count": { "type": "integer", "description": "命中次数。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间。" } } }, - "CreateAnnotationRequestCn": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" } } }, - "UpdateAnnotationRequestCn": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" } } }, - "InitialAnnotationReplySettingsRequestCn": { "type": "object", "required": ["score_threshold"], "properties": { "embedding_provider_name": { "type": "string", "nullable": true, "description": "指定的嵌入模型提供商名称。" }, "embedding_model_name": { "type": "string", "nullable": true, "description": "指定的嵌入模型名称。" }, "score_threshold": { "type": "number", "format": "float", "description": "相似度阈值。" } } }, - "InitialAnnotationReplySettingsResponseCn": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "job_status": { "type": "string", "description": "任务状态。" } } }, - "InitialAnnotationReplySettingsStatusResponseCn": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "job_status": { "type": "string", "description": "任务状态。" }, "error_msg": { "type": "string", "nullable": true, "description": "错误信息。" } } }, - "ErrorResponseCn": { "type": "object", "description": "错误响应。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTP 状态码。" }, "code": { "type": "string", "nullable": true, "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } + "EndUserDetail": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "终端用户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "租户 ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "应用 ID。" + }, + "type": { + "type": "string", + "description": "终端用户类型。Service API 用户固定为 `service_api`。" + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "API 请求中提供的 `user` 标识符（例如 [发送对话消息](/api-reference/对话消息/发送对话消息) 中的 `user` 字段）。" + }, + "name": { + "type": "string", + "nullable": true, + "description": "终端用户名称。" + }, + "is_anonymous": { + "type": "boolean", + "description": "用户是否为匿名用户。当原始 API 请求中未提供 `user` 标识符时，值为 `true`。" + }, + "session_id": { + "type": "string", + "description": "会话标识符。默认为 `external_user_id` 的值。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最后更新时间戳。" + } + } + }, + "MessageFeedbackRequest": { + "type": "object", + "description": "提交消息反馈的请求体。", + "required": [ + "user" + ], + "properties": { + "rating": { + "type": "string", + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "反馈评分。设为 `null` 可撤销之前提交的反馈。" + }, + "user": { + "type": "string", + "description": "用户标识符，由开发者定义，必须确保在应用内唯一。" + }, + "content": { + "type": "string", + "description": "提供额外详情的可选文字反馈。" + } + } + }, + "AppFeedbacksResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "反馈项列表。", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } + } + } + }, + "FeedbackItem": { + "type": "object", + "description": "单条反馈项。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "反馈 ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "应用 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。" + }, + "rating": { + "type": "string", + "description": "反馈评分。`like` 为正面，`dislike` 为负面。" + }, + "content": { + "type": "string", + "nullable": true, + "description": "可选的文字反馈。" + }, + "from_source": { + "type": "string", + "description": "反馈来源。`user` 为终端用户通过 API 提交的反馈，`admin` 为从控制台提交的反馈。" + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "提交反馈的终端用户 ID。当 `from_source` 为 `user` 时存在。" + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "提交反馈的账户 ID。当 `from_source` 为 `admin` 时存在。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最后更新时间戳。" + } + } + }, + "SuggestedQuestionsResponse": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "结果状态。" + }, + "data": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议问题列表。" + } + } + }, + "ConversationHistoryResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "has_more": { + "type": "boolean", + "description": "是否有更多消息。" + }, + "data": { + "type": "array", + "description": "消息列表。", + "items": { + "$ref": "#/components/schemas/ConversationMessageItem" + } + } + } + }, + "ConversationMessageItem": { + "type": "object", + "description": "会话中的单条消息。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "parent_message_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "线程会话的父消息 ID。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "该消息的输入变量。" + }, + "query": { + "type": "string", + "description": "用户查询文本。" + }, + "answer": { + "type": "string", + "description": "助手回答文本。" + }, + "status": { + "type": "string", + "description": "消息状态。成功消息为 `normal`，生成失败时为 `error`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "当 `status` 为 `error` 时的错误消息。" + }, + "message_files": { + "type": "array", + "description": "附加到该消息的文件。", + "items": { + "$ref": "#/components/schemas/MessageFileItem" + } + }, + "feedback": { + "type": "object", + "nullable": true, + "description": "该消息的用户反馈。", + "properties": { + "rating": { + "type": "string", + "description": "反馈评分。`like` 为正面，`dislike` 为负面。" + } + } + }, + "retriever_resources": { + "type": "array", + "description": "该消息使用的检索资源。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + }, + "agent_thoughts": { + "type": "array", + "description": "该消息的 Agent 思考。", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳（Unix 纪元秒）。" + }, + "extra_contents": { + "type": "array", + "description": "与此消息关联的附加执行内容，例如对话流工作流中人工介入节点的表单数据。", + "items": { + "$ref": "#/components/schemas/HumanInputContent" + } + } + } + }, + "MessageFileItem": { + "type": "object", + "description": "附加到消息的文件。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "原始文件名。" + }, + "type": { + "type": "string", + "description": "文件类型，例如 `image`。" + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "文件的预览 URL。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "文件的 MIME 类型。" + }, + "size": { + "type": "integer", + "nullable": true, + "description": "文件大小（字节）。" + }, + "transfer_method": { + "type": "string", + "description": "使用的传输方式。`remote_url` 表示基于 URL 的文件，`local_file` 表示已上传的文件，`tool_file` 表示工具生成的文件。" + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "该文件的所属者。用户上传的文件为 `user`，助手生成的文件为 `assistant`。" + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "通过 `local_file` 传输时的上传文件 ID。" + } + } + }, + "AgentThoughtItem": { + "type": "object", + "description": "消息中的 Agent 思考步骤。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Agent 思考 ID。" + }, + "chain_id": { + "type": "string", + "nullable": true, + "description": "该思考的链 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "该思考所属的唯一消息 ID。" + }, + "position": { + "type": "integer", + "description": "该思考的位置。" + }, + "thought": { + "type": "string", + "description": "LLM 正在思考的内容。" + }, + "tool": { + "type": "string", + "description": "调用的工具，以 `;` 分隔。" + }, + "tool_labels": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "已使用工具的标签。" + }, + "tool_input": { + "type": "string", + "description": "工具输入（JSON 格式）。" + }, + "observation": { + "type": "string", + "description": "工具调用的响应。" + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "与该思考相关的文件 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + } + } + }, + "ConversationsListResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "has_more": { + "type": "boolean", + "description": "是否有更多会话。" + }, + "data": { + "type": "array", + "description": "会话列表。", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } + } + } + }, + "ConversationListItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "name": { + "type": "string", + "description": "会话名称。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "会话的输入变量。" + }, + "status": { + "type": "string", + "description": "会话状态。活跃会话为 `normal`。" + }, + "introduction": { + "type": "string", + "description": "会话介绍。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最后更新时间戳。" + } + } + }, + "ConversationRenameRequest": { + "type": "object", + "description": "重命名会话的请求体。", + "required": [ + "user" + ], + "properties": { + "name": { + "type": "string", + "description": "会话名称。当 `auto_generate` 为 `false` 时必填。" + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "自动生成会话名称。当为 `true` 时，`name` 字段将被忽略。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "ConversationVariablesResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "has_more": { + "type": "boolean", + "description": "是否有下一页。" + }, + "data": { + "type": "array", + "description": "会话变量列表。", + "items": { + "$ref": "#/components/schemas/ConversationVariableItem" + } + } + } + }, + "ConversationVariableItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Variable ID." + }, + "name": { + "type": "string", + "description": "变量名称。" + }, + "value_type": { + "type": "string", + "description": "变量值类型。可选值：`string`、`number`、`object`、`secret`、`file`、`boolean`、`array[any]`、`array[string]`、`array[number]`、`array[object]`、`array[file]`、`array[boolean]`。" + }, + "value": { + "type": "string", + "description": "变量值（复杂类型可以是 JSON 字符串）。" + }, + "description": { + "type": "string", + "description": "变量描述。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最后更新时间戳。" + } + } + }, + "ConversationVariableUpdateRequest": { + "type": "object", + "description": "更新会话变量的请求体。", + "required": [ + "value" + ], + "properties": { + "value": { + "description": "变量的新值。必须与变量的预期类型匹配。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "语音转文字的请求体。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音频文件。支持格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。大小限制：`30 MB`。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "语音识别输出的文字。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "文字转语音的请求体。提供 `message_id` 或 `text` 其中之一。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。当同时提供 `text` 时，优先使用消息 ID。" + }, + "text": { + "type": "string", + "description": "要转换的语音内容。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + }, + "voice": { + "type": "string", + "description": "文字转语音使用的声音。可用声音取决于为此应用配置的 TTS 提供商。使用[获取应用参数](/api-reference/应用配置/获取应用参数) → `text_to_speech.voice` 中的 `voice` 值作为默认值。" + }, + "streaming": { + "type": "boolean", + "description": "是否启用流式响应。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "应用名称。" + }, + "description": { + "type": "string", + "description": "应用描述。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "应用标签。" + }, + "mode": { + "type": "string", + "description": "应用模式。`completion` 为文本生成应用，`chat` 为基础对话应用，`agent-chat` 为 Agent 应用，`advanced-chat` 为对话流应用，`workflow` 为工作流应用。" + }, + "author_name": { + "type": "string", + "description": "应用作者名称。" + } + } + }, + "ChatAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "会话开始时显示的开场白。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议的初始问题列表。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答后建议问题的配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "语音转文字配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "文字转语音配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + }, + "voice": { + "type": "string", + "description": "TTS 的声音标识符。" + }, + "language": { + "type": "string", + "description": "TTS 的语言。" + }, + "autoPlay": { + "type": "string", + "description": "自动播放设置。`enabled` 为自动播放音频，`disabled` 为需要手动播放。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "检索资源配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "标注回复配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "更多类似内容配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "敏感词过滤配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "user_input_form": { + "type": "array", + "description": "用户输入表单元素列表。", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "文件上传配置。", + "properties": { + "image": { + "type": "object", + "description": "图片上传设置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用图片上传。" + }, + "number_limits": { + "type": "integer", + "description": "最大图片数量。" + }, + "detail": { + "type": "string", + "description": "图片精细程度。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "允许的传输方式。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "系统级参数和限制。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "最大文件大小（MB）。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最大图片文件大小（MB）。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最大音频文件大小（MB）。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最大视频文件大小（MB）。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "工作流文件上传的最大文件数。" + } + } + } + } + }, + "UserInputFormItem": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } + ] + }, + "TextInputControlWrapper": { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } + }, + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } + }, + "SelectControlWrapper": { + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } + }, + "TextInputControl": { + "type": "object", + "description": "文本输入表单控件。", + "properties": { + "label": { + "type": "string", + "description": "显示标签。" + }, + "variable": { + "type": "string", + "description": "变量名称。" + }, + "required": { + "type": "boolean", + "description": "输入是否必填。" + }, + "default": { + "type": "string", + "description": "默认值。" + } + } + }, + "ParagraphControl": { + "type": "object", + "description": "段落（多行文本）表单控件。", + "properties": { + "label": { + "type": "string", + "description": "显示标签。" + }, + "variable": { + "type": "string", + "description": "变量名称。" + }, + "required": { + "type": "boolean", + "description": "输入是否必填。" + }, + "default": { + "type": "string", + "description": "默认值。" + } + } + }, + "SelectControl": { + "type": "object", + "description": "下拉选择表单控件。", + "properties": { + "label": { + "type": "string", + "description": "显示标签。" + }, + "variable": { + "type": "string", + "description": "变量名称。" + }, + "required": { + "type": "boolean", + "description": "是否必须选择。" + }, + "default": { + "type": "string", + "description": "默认选中的值。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "此表单控件的可选值列表。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "图标的 URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "工具图标。键为工具名称。" + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "使用 emoji 的工具图标详情。", + "properties": { + "background": { + "type": "string", + "description": "十六进制格式的背景颜色。" + }, + "content": { + "type": "string", + "description": "Emoji 内容。" + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp 标题。" + }, + "chat_color_theme": { + "type": "string", + "description": "聊天主题颜色。" + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "聊天主题颜色是否反转。" + }, + "icon_type": { + "type": "string", + "description": "使用的图标类型。`emoji` 为表情图标，`image` 为上传的图片图标。" + }, + "icon": { + "type": "string", + "description": "图标内容（表情或图片 ID）。" + }, + "icon_background": { + "type": "string", + "description": "图标背景颜色。" + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "图标图片的 URL。" + }, + "description": { + "type": "string", + "description": "WebApp 描述。" + }, + "copyright": { + "type": "string", + "description": "版权文本。" + }, + "privacy_policy": { + "type": "string", + "description": "隐私政策 URL。" + }, + "custom_disclaimer": { + "type": "string", + "description": "自定义免责声明文本。" + }, + "default_language": { + "type": "string", + "description": "默认语言代码。" + }, + "show_workflow_steps": { + "type": "boolean", + "description": "是否显示工作流步骤。" + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "是否使用应用图标作为回答图标。" + } + } + }, + "AnnotationListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "description": "当前页面的标注项列表。" + }, + "has_more": { + "type": "boolean", + "description": "如果当前结果集之后还有更多页面，则为 `true`。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "匹配查询条件的标注总数。" + }, + "page": { + "type": "integer", + "description": "当前页码。" + } + } + }, + "AnnotationItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "标注唯一标识符。" + }, + "question": { + "type": "string", + "nullable": true, + "description": "触发该标注的问题文本。" + }, + "answer": { + "type": "string", + "nullable": true, + "description": "标注被匹配时返回的预定义回答。" + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "该标注被匹配并作为回复返回的次数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "创建时间戳（Unix 纪元秒）。" + } + } + }, + "CreateAnnotationRequest": { + "type": "object", + "description": "创建新标注的请求体。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "标注问题。" + }, + "answer": { + "type": "string", + "description": "标注答案。" + } + } + }, + "UpdateAnnotationRequest": { + "type": "object", + "description": "更新标注的请求体。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "更新后的标注问题。" + }, + "answer": { + "type": "string", + "description": "更新后的标注答案。" + } + } + }, + "InitialAnnotationReplySettingsRequest": { + "type": "object", + "description": "配置标注回复设置的请求体。", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], + "properties": { + "embedding_provider_name": { + "type": "string", + "description": "嵌入模型提供商名称（例如 `openai`、`cohere`）。" + }, + "embedding_model_name": { + "type": "string", + "description": "用于标注匹配的嵌入模型名称（例如 `text-embedding-3-small`）。" + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "标注被视为匹配的最低相似度分数。值越高，要求匹配越精确。", + "minimum": 0, + "maximum": 1 + } + } + }, + "InitialAnnotationReplySettingsResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "异步任务 ID。配合 [查询标注回复配置任务状态](/api-reference/标注管理/查询标注回复配置任务状态) 使用以跟踪进度。" + }, + "job_status": { + "type": "string", + "description": "当前任务状态。`waiting` 表示排队中，`processing` 表示处理中，`completed` 表示已完成，`error` 表示失败。" + } + } + }, + "InitialAnnotationReplySettingsStatusResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "来自 [配置标注回复](/api-reference/标注管理/配置标注回复) 调用的任务 ID。" + }, + "job_status": { + "type": "string", + "description": "当前任务状态。`waiting` 表示排队中，`processing` 表示处理中，`completed` 表示已完成，`error` 表示失败。" + }, + "error_msg": { + "type": "string", + "description": "描述任务失败原因的错误消息。当 `job_status` 不是 `error` 时为空字符串。" + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "工作流执行已开始。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "工作流运行 ID。" + }, + "workflow_id": { + "type": "string", + "description": "关联的工作流 ID。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "本次工作流执行的输入变量。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "开始时间戳（Unix 纪元秒）。" + }, + "reason": { + "type": "string", + "description": "工作流启动原因。`initial` 表示首次启动，`resumption` 表示暂停后恢复（例如人工介入后）。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "工作流执行已完成。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "工作流运行 ID。" + }, + "workflow_id": { + "type": "string", + "description": "关联的工作流 ID。" + }, + "status": { + "type": "string", + "description": "执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`stopped` 表示手动停止，`partial-succeeded` 表示部分完成，`paused` 表示等待人工介入。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "工作流输出数据。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "执行失败时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "总执行耗时（秒）。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总令牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的总步数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "开始时间戳（Unix 纪元秒）。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "结束时间戳（Unix 纪元秒）。" + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "执行期间的异常数量。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "工作流执行期间生成的文件。" + } + } + } + } + } + ] + }, + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "节点执行已开始。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工作流图中的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "节点类型（例如 `llm`、`knowledge-retrieval`、`code`）。" + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "执行索引。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点输入数据。在简化 API 响应中可能为 `null`。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "开始时间戳（Unix 纪元秒）。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "如果该节点在迭代内运行，则为迭代 ID。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "当该节点在循环内运行时的循环 ID。" + } + } + } + } + } + ] + }, + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "节点执行已完成。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工作流图中的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "执行索引。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点输入数据。在简化 API 响应中可能为 `null`。" + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点处理数据。在简化 API 响应中可能为 `null`。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点输出数据。在简化 API 响应中可能为 `null`。" + }, + "status": { + "type": "string", + "description": "节点执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "节点失败时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "节点执行耗时（秒）。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "执行元数据（例如令牌用量、模型信息）。在简化 API 响应中可能为 `null`。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "开始时间戳（Unix 纪元秒）。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "结束时间戳（Unix 纪元秒）。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "该节点生成的文件。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "如果该节点在迭代内运行，则为迭代 ID。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "当该节点在循环内运行时的循环 ID。" + } + } + } + } + } + ] + }, + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "节点重试次数。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工作流图中的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "执行索引。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点输入数据。" + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点处理数据。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点输出数据。" + }, + "status": { + "type": "string", + "description": "节点执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "本次重试的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "本次尝试的执行时间（秒）。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "执行元数据。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "开始时间戳（Unix 纪元秒）。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "结束时间戳（Unix 纪元秒）。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "本次重试期间生成的文件。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "迭代 ID（如适用）。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "循环 ID（如适用）。" + }, + "retry_index": { + "type": "integer", + "description": "重试次数索引，从 `0` 开始。" + } + } + } + } + } + ] + }, + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "迭代循环已开始。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "迭代执行 ID。" + }, + "node_id": { + "type": "string", + "description": "迭代节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "迭代节点标题。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "开始时间戳（Unix 纪元秒）。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "迭代元数据。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "迭代输入数据。" + } + } + } + } + } + ] + }, + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "迭代已进入下一项。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "迭代执行 ID。" + }, + "node_id": { + "type": "string", + "description": "迭代节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "迭代节点标题。" + }, + "index": { + "type": "integer", + "description": "当前迭代索引（从 0 开始）。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "时间戳（Unix 纪元秒）。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "迭代循环已完成。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "迭代执行 ID。" + }, + "node_id": { + "type": "string", + "description": "迭代节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "迭代节点标题。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "迭代输出数据。" + }, + "status": { + "type": "string", + "description": "迭代执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "迭代失败时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "迭代总耗时（秒）。" + }, + "total_tokens": { + "type": "integer", + "description": "所有迭代中消耗的令牌总数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "开始时间戳（Unix 纪元秒）。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "结束时间戳（Unix 纪元秒）。" + }, + "steps": { + "type": "integer", + "description": "已执行的迭代步骤总数。" + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "循环已开始。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "循环执行 ID。" + }, + "node_id": { + "type": "string", + "description": "循环节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "循环节点标题。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "开始时间戳（Unix 纪元秒）。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "循环元数据。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "循环输入数据。" + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "循环已进入下一次迭代。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "循环执行 ID。" + }, + "node_id": { + "type": "string", + "description": "循环节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "循环节点标题。" + }, + "index": { + "type": "integer", + "description": "当前循环索引（从 0 开始）。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "时间戳（Unix 纪元秒）。" + }, + "pre_loop_output": { + "description": "上一次循环迭代的输出。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "循环已完成。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "循环执行 ID。" + }, + "node_id": { + "type": "string", + "description": "循环节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "循环节点标题。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "循环输出数据。" + }, + "status": { + "type": "string", + "description": "循环执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "循环失败时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "循环总执行耗时（秒）。" + }, + "total_tokens": { + "type": "integer", + "description": "所有循环迭代中消耗的令牌总数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "开始时间戳（Unix 纪元秒）。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "结束时间戳（Unix 纪元秒）。" + }, + "steps": { + "type": "integer", + "description": "已执行的循环总步数。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "人工介入节点正在等待用户输入。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "用于提交响应的表单 ID。" + }, + "node_id": { + "type": "string", + "description": "人工介入节点的节点 ID。" + }, + "node_title": { + "type": "string", + "description": "人工介入节点的标题。" + }, + "form_content": { + "type": "string", + "description": "给用户的表单内容/说明。" + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "表单输入字段定义。" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "可用的用户操作。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "表单提交认证的令牌。" + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "表单过期的 Unix 时间戳。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/工作流/获取-工作流-执行情况) 使用以在执行后获取结果。" + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "已暂停的节点 ID 列表。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "暂停时的部分输出。" + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "暂停原因。" + }, + "status": { + "type": "string", + "description": "工作流执行状态。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时（秒）。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总令牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的总步数。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "表单提交后的渲染内容。" + }, + "action_id": { + "type": "string", + "description": "已执行操作的 ID。" + }, + "action_text": { + "type": "string", + "description": "已执行操作的文本。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工作流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "表单过期的 Unix 时间戳。" + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "工作流中 Agent 节点的 Agent 日志。", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "节点执行 ID。" + }, + "id": { + "type": "string", + "description": "日志条目 ID。" + }, + "label": { + "type": "string", + "description": "日志条目标签。" + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "嵌套条目的父日志条目 ID。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "错误消息（如适用）。" + }, + "status": { + "type": "string", + "description": "日志条目状态。" + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "日志条目数据。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + }, + "node_id": { + "type": "string", + "description": "工作流图中的节点 ID。" + } + } + } + } + } + ] + }, + "StreamEventChatTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "文本内容块。" + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "工作流中文本变量的源路径。" + } + } + } + } + } + ] + }, + "StreamEventChatTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "替换的文本内容。" + } + } + } + } + } + ] + }, + "WorkflowRunDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工作流运行 ID。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "工作流 ID." + }, + "status": { + "type": "string", + "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "工作流运行的输入变量。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "工作流的输出数据。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工作流失败时的错误消息。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工作流总步数。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总令牌数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工作流运行创建时的 Unix 时间戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工作流运行结束时的 Unix 时间戳。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "总耗时（秒）。" + } + } + }, + "WorkflowLogsResponse": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "description": "当前页码。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "日志条目总数。" + }, + "has_more": { + "type": "boolean", + "description": "是否有更多可用页面。" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "工作流日志条目列表。" + } + } + }, + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "日志条目 ID。" + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "工作流运行的来源（例如 `service-api`）。" + }, + "created_by_role": { + "type": "string", + "description": "创建者的角色（例如 `end_user`、`account`）。" + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "由管理员用户创建时的账户详情。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "账户 ID。" + }, + "name": { + "type": "string", + "description": "账户显示名称。" + }, + "email": { + "type": "string", + "description": "账户邮箱地址。" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "日志条目创建时的 Unix 时间戳。" + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "日志条目的附加详情。" + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工作流运行 ID。" + }, + "version": { + "type": "string", + "description": "工作流版本标识符。" + }, + "status": { + "type": "string", + "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工作流失败时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时（秒）。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总令牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工作流总步数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工作流运行创建时的 Unix 时间戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工作流运行结束时的 Unix 时间戳。" + }, + "exceptions_count": { + "type": "integer", + "description": "执行期间发生的异常数量。" + }, + "triggered_from": { + "type": "string", + "description": "触发工作流运行的来源。`debugging` 表示从编辑器发起的测试运行，`app` 表示 API 或应用发起的运行。" + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "终端用户 ID。" + }, + "type": { + "type": "string", + "description": "终端用户类型。" + }, + "is_anonymous": { + "type": "boolean", + "description": "终端用户是否为匿名。" + }, + "session_id": { + "type": "string", + "description": "会话标识符。" + } + } + }, + "HumanInputContent": { + "type": "object", + "description": "人工介入节点的执行内容，包括表单定义和提交数据。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "该内容所属的工作流运行 ID。" + }, + "submitted": { + "type": "boolean", + "description": "人工介入表单是否已提交。" + }, + "type": { + "type": "string", + "description": "`human_input` 表示人工介入内容。" + }, + "form_definition": { + "nullable": true, + "description": "人工介入节点的表单定义。当内容表示提交响应时为 `null`。", + "$ref": "#/components/schemas/HumanInputFormDefinition" + }, + "form_submission_data": { + "nullable": true, + "description": "已提交的表单数据。表单尚未提交时为 `null`。", + "$ref": "#/components/schemas/HumanInputFormSubmissionData" + } + } + }, + "HumanInputFormDefinition": { + "type": "object", + "description": "由人工介入节点渲染的人工介入表单定义。", + "properties": { + "form_id": { + "type": "string", + "description": "表单唯一标识符。" + }, + "node_id": { + "type": "string", + "description": "生成该表单的人工介入节点 ID。" + }, + "node_title": { + "type": "string", + "description": "人工介入节点的标题。" + }, + "form_content": { + "type": "string", + "description": "与表单一起显示的 Markdown 或文本内容。" + }, + "inputs": { + "type": "array", + "description": "表单中的输入字段。", + "items": { + "$ref": "#/components/schemas/FormInput" + } + }, + "actions": { + "type": "array", + "description": "表单上可用的操作按钮。", + "items": { + "$ref": "#/components/schemas/UserAction" + } + }, + "display_in_ui": { + "type": "boolean", + "description": "表单是否应在 UI 中显示。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "表单提交认证的令牌。" + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "表单输入的已解析默认值，按输出变量名称索引。" + }, + "expiration_time": { + "type": "integer", + "description": "表单过期的 Unix 时间戳。" + } + } + }, + "HumanInputFormSubmissionData": { + "type": "object", + "description": "来自已提交的人工介入表单的数据。", + "properties": { + "node_id": { + "type": "string", + "description": "人工介入节点的 ID。" + }, + "node_title": { + "type": "string", + "description": "人工介入节点的标题。" + }, + "rendered_content": { + "type": "string", + "description": "表单提交的渲染内容。" + }, + "action_id": { + "type": "string", + "description": "被点击的操作按钮的 ID。" + }, + "action_text": { + "type": "string", + "description": "被点击的操作按钮的显示文本。" + } + } + }, + "FormInput": { + "type": "object", + "description": "表单输入字段定义。", + "properties": { + "type": { + "type": "string", + "description": "`text_input` 为单行文本，`paragraph` 为多行文本。" + }, + "output_variable_name": { + "type": "string", + "description": "存储输入值的变量名称。" + }, + "default": { + "nullable": true, + "description": "该输入的默认值配置。", + "$ref": "#/components/schemas/FormInputDefault" + } + } + }, + "FormInputDefault": { + "type": "object", + "description": "表单输入的默认值配置。", + "properties": { + "type": { + "type": "string", + "description": "`variable` for dynamic values from 工作流 variables, `constant` for static values." + }, + "selector": { + "type": "array", + "items": { + "type": "string" + }, + "description": "当 `type` 为 `variable` 时的变量选择器路径。" + }, + "value": { + "type": "string", + "description": "当 `type` 为 `constant` 时的静态值。" + } + } + }, + "UserAction": { + "type": "object", + "description": "人工介入表单上的操作按钮。", + "properties": { + "id": { + "type": "string", + "description": "操作唯一标识符。" + }, + "title": { + "type": "string", + "description": "按钮显示文本。" + }, + "button_style": { + "type": "string", + "description": "`primary`, `default`, `accent`, or `ghost`." + } + } + } } }, "tags": [ - { "name": "对话消息", "description": "与对话消息和交互相关的操作。" }, - { "name": "文件操作", "description": "文件上传和预览相关的操作。" }, - { "name": "终端用户", "description": "终端用户信息相关的操作。" }, - { "name": "消息反馈", "description": "用户对消息的反馈操作。" }, - { "name": "会话管理", "description": "管理对话会话相关的操作。" }, - { "name": "语音与文字转换", "description": "文本转语音和语音转文本操作。" }, - { "name": "应用配置", "description": "获取应用设置和信息相关的操作。" }, - { "name": "标注管理", "description": "管理用于直接回复的标注数据。" } + { + "name": "对话消息", + "description": "与聊天消息和交互相关的操作。" + }, + { + "name": "文件操作", + "description": "文件上传和预览操作。" + }, + { + "name": "终端用户", + "description": "终端用户信息相关操作。" + }, + { + "name": "消息反馈", + "description": "用户反馈操作。" + }, + { + "name": "会话管理", + "description": "与管理会话相关的操作。" + }, + { + "name": "语音与文字转换", + "description": "文字转语音和语音转文字操作。" + }, + { + "name": "应用配置", + "description": "获取应用设置和信息的操作。" + }, + { + "name": "标注管理", + "description": "与管理标注直接回复相关的操作。" + }, + { + "name": "工作流执行", + "description": "与工作流执行详情和日志相关的操作。" + } ] -} \ No newline at end of file +} diff --git a/zh/api-reference/openapi_completion.json b/zh/api-reference/openapi_completion.json index 27b14909..43bff9e0 100644 --- a/zh/api-reference/openapi_completion.json +++ b/zh/api-reference/openapi_completion.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "文本生成型应用 API", - "description": "文本生成应用无会话支持，适合用于翻译/文章写作/总结 AI 等等。", + "description": "文本生成型应用提供无会话支持，适用于翻译、文章撰写、摘要总结 AI 等场景。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API 的基础 URL。请将 {api_base_url} 替换为你的应用提供的实际 API 基础 URL。", + "description": "文本生成型应用 API 的基础 URL。请将 {api_base_url} 替换为你的应用实际提供的 API 基础 URL。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "实际的 API 基础 URL" + "description": "API 的实际基础 URL" } } } @@ -26,11 +26,13 @@ "/completion-messages": { "post": { "summary": "发送消息", - "description": "发送请求给文本生成型应用。", + "description": "向文本生成型应用发送请求。", "operationId": "createCompletionMessage", - "tags": ["文本生成"], + "tags": [ + "文本生成" + ], "requestBody": { - "description": "创建完成消息的请求体。", + "description": "创建文本生成消息的请求体。", "required": true, "content": { "application/json": { @@ -39,11 +41,32 @@ }, "examples": { "streaming_example": { - "summary": "流式模式示例", + "summary": "请求示例 - 流式模式", "value": { - "inputs": {"query": "你好，世界！"}, + "inputs": { + "city": "San Francisco" + }, + "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", - "user": "abc-123" + "user": "abc-123", + "files": [ + { + "type": "image", + "transfer_method": "remote_url", + "url": "https://cloud.dify.ai/logo/logo-site.png" + } + ] + } + }, + "blocking_example": { + "summary": "请求示例 - 阻塞模式", + "value": { + "inputs": { + "city": "New York" + }, + "query": "Summarize the following text: ...", + "response_mode": "blocking", + "user": "def-456" } } } @@ -52,140 +75,137 @@ }, "responses": { "200": { - "description": "成功响应。内容类型和结构取决于请求中的 `response_mode` 参数。\n- 若 `response_mode` 为 `blocking`，返回 `application/json` 及 `ChatCompletionResponse` 对象。\n- 若 `response_mode` 为 `streaming`，返回 `text/event-stream` 及 `ChunkChatCompletionResponse` 流式序列。", + "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `CompletionResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkCompletionEvent` 对象流。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatCompletionResponse" + "$ref": "#/components/schemas/CompletionResponse" }, "examples": { - "blockingResponse": { - "summary": "阻塞模式响应示例", - "value": { - "id": "0b089b9a-24d9-48cc-94f8-762677276261", - "message_id": "0b089b9a-24d9-48cc-94f8-762677276261", - "mode": "chat", - "answer": "how are you?", - "metadata": {}, - "created_at": 1679586667 + "blockingResponse": { + "summary": "响应示例 - 阻塞模式", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "mode": "completion", + "answer": "Hello World!...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 } + }, + "created_at": 1705407629 } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "服务器发送事件 (SSE) 流。每个事件都是以 'data: ' 开头，以 '\\n\\n' 结尾的 JSON 对象。详见 `ChunkEvent` 的可能结构。" + "description": "服务器发送事件 (SSE) 流。每个事件是一个以 `data: ` 为前缀的 JSON 对象，以两个换行符终止。\n\n**SSE 解析指南：**每个事件是一行以 `data: ` 为前缀的 JSON 对象，以 `\\n\\n` 终止。解析 JSON 前先去除 `data: ` 前缀。JSON 内的 `event` 字段决定事件类型。当收到终止事件（如 `message_end` 或 `error`）时流结束。忽略 `ping` 事件（每 10 秒发送一次以保持连接活跃）。注意即使流中出现错误事件，HTTP 状态码仍为 `200`。" }, "examples": { "streamingResponse": { - "summary": "流式模式响应示例", - "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"663c5084-a254-4040-8ad3-51f2a3c1a77c\", \"message_id\": \"663c5084-a254-4040-8ad3-51f2a3c1a77c\", \"answer\": \"Hi\", \"created_at\": 1705398420}\n\ndata: {\"event\": \"tts_message\", \"task_id\": \"3bf8a0bb-e73b-4690-9e66-4e429bad8ee7\", \"message_id\": \"a8bdc41c-13b2-4c18-bfd9-054b9803038c\", \"audio\": \"base64encodedaudio...\", \"created_at\": 1721205487}\n\n" + "summary": "响应示例 - 流式模式", + "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n" } } } } }, - "400": { "$ref": "#/components/responses/BadRequestCompletion" }, - "404": { "$ref": "#/components/responses/ConversationNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } - } - } - }, - "/files/upload": { - "post": { - "summary": "上传文件", - "description": "上传文件（目前仅支持图片）并在发送消息时使用，可实现图文多模态理解。支持 png, jpg, jpeg, webp, gif 格式。上传的文件仅供当前终端用户使用。", - "operationId": "uploadFile", - "tags": ["文件管理"], - "requestBody": { - "description": "文件上传请求，需使用 `multipart/form-data`。", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "要上传的文件。支持的图片类型：png, jpg, jpeg, webp, gif。" + "400": { + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 文本生成失败。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } }, - "user": { - "type": "string", - "description": "用户标识，由开发者定义规则，需保证用户标识在应用内唯一，必须和发送消息接口传入 user 保持一致。" + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } } } } } - } - }, - "responses": { - "200": { - "description": "文件上传成功。", + }, + "429": { + "description": "`too_many_requests` : 该应用的并发请求过多。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponse" + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + } } } } }, - "201": { - "description": "文件创建成功 (备选成功状态码)。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponse" - } - } - } - }, - "400": { "$ref": "#/components/responses/BadRequestFile" }, - "413": { "$ref": "#/components/responses/FileTooLarge" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFile" }, - "503": { "$ref": "#/components/responses/S3ErrorFile" } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "获取终端用户", - "description": "通过 ID 获取终端用户信息。\n\n当其他 API 返回终端用户 ID（例如文件上传接口返回的 `created_by`）时，可使用该接口查询对应的终端用户信息。", - "operationId": "getEndUserCompletionCn", - "tags": ["终端用户"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "终端用户 ID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "responses": { - "200": { - "description": "成功获取终端用户信息。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetail" } - } - } - }, - "404": { - "description": "终端用户不存在。错误码：`end_user_not_found`", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, "500": { - "description": "服务内部异常。", + "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -195,16 +215,20 @@ "/completion-messages/{task_id}/stop": { "post": { "summary": "停止响应", - "description": "停止生成任务，仅支持流式模式。", + "description": "停止文本生成消息生成任务。仅在 `streaming` 模式下支持。", "operationId": "stopCompletionGeneration", - "tags": ["文本生成"], + "tags": [ + "文本生成" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "任务 ID，可在流式返回 Chunk 中获取。", - "schema": { "type": "string", "format": "uuid" } + "description": "任务 ID，可以从 [发送消息](/api-reference/文本生成/发送消息) API 的流式分块返回中获取。", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -213,11 +237,21 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { "user": { "type": "string", - "description": "用户标识，必须和发送消息接口传入 user 保持一致。" + "description": "用户标识符，必须和发送消息接口传入的 user 保持一致。" + } + } + }, + "examples": { + "example": { + "summary": "请求示例", + "value": { + "user": "abc-123" } } } @@ -225,54 +259,615 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`app_unavailable` : 应用不可用或配置错误。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } } } }, "/messages/{message_id}/feedbacks": { "post": { - "summary": "消息反馈（点赞）", - "description": "消息终端用户反馈、点赞，方便应用开发者优化输出预期。", "operationId": "postMessageFeedback", - "tags": ["反馈"], + "tags": [ + "消息反馈" + ], + "summary": "提交消息反馈", + "description": "提交消息反馈。终端用户可以对消息评价 `like` 或 `dislike`，并可选择提供文字反馈。将 `rating` 设为 `null` 可撤销之前提交的反馈。", "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string" + } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequest" } + "schema": { + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "请求示例", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } + } } } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : 消息不存在。", + "content": { + "application/json": { + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } + } + } + } } } }, "/app/feedbacks": { "get": { - "summary": "获取应用反馈列表", - "description": "获取应用的反馈信息。", "operationId": "getAppFeedbacks", - "tags": ["反馈"], + "tags": [ + "消息反馈" + ], + "summary": "获取应用的消息反馈", + "description": "获取此应用中所有消息反馈的分页列表，包括终端用户和管理员反馈。", "parameters": [ - { "$ref": "#/components/parameters/PageQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20" } + { + "name": "page", + "in": "query", + "description": "分页页码。", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页记录数。", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } + } ], "responses": { "200": { - "description": "成功获取应用反馈列表。", + "description": "应用反馈列表。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponse" } + "schema": { + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "rating": "like", + "content": "The response accurately answered my question about product specifications.", + "from_source": "user", + "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "from_account_id": null, + "created_at": "2025-01-16T14:30:29Z", + "updated_at": "2025-01-16T14:30:29Z" + }, + { + "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", + "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", + "rating": "dislike", + "content": "The answer was too vague and did not address the specific pricing question.", + "from_source": "user", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", + "from_account_id": null, + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" + } + ] + } + } + } + } + } + } + } + } + }, + "/files/upload": { + "post": { + "operationId": "uploadFile", + "tags": [ + "文件操作" + ], + "summary": "上传文件", + "description": "上传文件用于发送消息时使用，支持图片、文档、音频和视频的多模态理解。上传的文件仅供当前终端用户使用。", + "requestBody": { + "description": "文件上传请求。需要 multipart/form-data 格式。", + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "要上传的文件。支持的类型包括图片、文档、音频和视频。" + }, + "user": { + "type": "string", + "description": "用户标识符，由开发者定义的规则生成，必须在应用内唯一。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "文件上传成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : 请求中未提供文件。\n- `too_many_files` : 每次请求仅允许上传一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : 文件大小超出限制。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 不允许的文件类型。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { + "get": { + "operationId": "previewCompletionFileZh", + "tags": [ + "文件操作" + ], + "summary": "下载文件", + "description": "预览或下载之前通过[上传文件](/api-reference/文件操作/上传文件) API 上传的文件。仅可访问属于请求应用内消息的文件。", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "要预览的文件唯一标识符，从 [上传文件](/api-reference/文件操作/上传文件) API 响应中获取。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "如果为 `true`，则强制文件以附件形式下载，而不是在浏览器中预览。", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符，用于终端用户上下文。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "返回原始文件内容。`Content-Type` 头设置为文件的 MIME 类型。如果 `as_attachment` 为 `true`，文件将以 `Content-Disposition: attachment` 方式作为下载返回。", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : 拒绝访问请求的文件。", + "content": { + "application/json": { + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : 未找到请求的文件。", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "operationId": "getEndUserCompletionCn", + "tags": [ + "终端用户" + ], + "summary": "获取终端用户", + "description": "根据 ID 获取终端用户信息。当其他 API 返回终端用户 ID（例如[上传文件](/api-reference/文件操作/上传文件)返回的 `created_by`）时很有用。", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "终端用户 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "成功获取终端用户。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "响应示例", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : 未找到终端用户。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "completionAudioToTextZh", + "tags": [ + "语音与文字转换" + ], + "summary": "语音转文字", + "description": "将音频文件转换为文字。支持的格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件大小限制为 `30 MB`。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "语音转文字成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "响应示例", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `no_audio_uploaded` : 未上传音频文件。\n- `provider_not_support_speech_to_text` : 模型提供商不支持语音转文字。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 语音识别请求失败。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音频文件大小超出限制。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 不允许的音频类型。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -281,27 +876,109 @@ }, "/text-to-audio": { "post": { - "summary": "文字转语音", - "description": "将文本内容转换为语音。", "operationId": "textToAudio", - "tags": ["语音服务"], + "tags": [ + "语音与文字转换" + ], + "summary": "文字转语音", + "description": "将文字转换为语音。", "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/TextToAudioRequest" } + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "请求示例", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } } } }, "responses": { "200": { - "description": "语音文件生成成功。", + "description": "返回生成的音频文件。`Content-Type` 头设置为音频 MIME 类型（例如 `audio/wav`、`audio/mp3`）。如果 `streaming` 为 `true`，音频将以分块传输编码方式流式返回。", "content": { - "audio/wav": { "schema": { "type": "string", "format": "binary", "description": "生成的 WAV 格式音频文件。" } }, - "audio/mp3": { "schema": { "type": "string", "format": "binary", "description": "生成的 MP3 格式音频文件。" } } - }, - "headers": { - "Content-Type": { "schema": { "type": "string", "example": "audio/wav" }, "description": "响应的内容类型，通常为 `audio/wav` 或 `audio/mp3`。" } + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 文字转语音请求失败。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } } } } @@ -309,130 +986,239 @@ }, "/info": { "get": { - "summary": "获取应用基本信息", - "description": "用于获取此应用的基本信息。", "operationId": "getAppInfo", - "tags": ["应用设置"], + "tags": [ + "应用配置" + ], + "summary": "获取应用基本信息", + "description": "获取应用的基本信息，包括名称、描述、标签和模式。", "responses": { "200": { "description": "应用的基本信息。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponse" } } } + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "响应示例", + "value": { + "name": "My Completion App", + "description": "一个有用的客服聊天机器人。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "completion", + "author_name": "Dify Team" + } + } + } + } + } } } } }, "/parameters": { "get": { - "summary": "获取应用参数", - "description": "用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。", "operationId": "getAppParameters", - "tags": ["应用设置"], + "tags": [ + "应用配置" + ], + "summary": "获取应用参数", + "description": "获取应用的输入表单配置，包括功能开关、输入参数名称、类型和默认值。", "responses": { "200": { - "description": "应用的参数信息。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppParametersResponseCompletion" } } } + "description": "应用参数信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompletionAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "响应示例", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : 应用不可用或配置错误。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getCompletionAppMetaZh", + "tags": [ + "应用配置" + ], + "summary": "获取应用元数据", + "description": "获取应用的元数据，包括工具图标和其他配置详情。", + "responses": { + "200": { + "description": "成功获取应用元数据。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "响应示例", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } } } } }, "/site": { "get": { - "summary": "获取应用 WebApp 设置", - "description": "用于获取应用的 WebApp 设置。", "operationId": "getWebAppSettings", - "tags": ["应用设置"], + "tags": [ + "应用配置" + ], + "summary": "获取应用 WebApp 设置", + "description": "获取应用的 WebApp 设置，包括站点配置、主题和自定义选项。", "responses": { "200": { - "description": "应用的 WebApp 设置信息。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" } } } + "description": "应用的 WebApp 设置。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "响应示例", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "一个有用的客服聊天机器人。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 未找到此应用的站点或工作空间已归档。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } } } } - }, - "/apps/annotations": { - "get": { - "summary": "获取标注列表", - "description": "获取应用的标注列表。", - "operationId": "getAnnotationList", - "tags": ["标注管理"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamAnnotation" } - ], - "responses": { - "200": { "description": "成功获取标注列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationListResponse" } } } } - } - }, - "post": { - "summary": "创建标注", - "description": "创建一个新的标注。", - "operationId": "createAnnotation", - "tags": ["标注管理"], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" } } } - }, - "responses": { - "200": { "description": "标注创建成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } }, - "201": { "description": "标注创建成功 (备选)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } } - } - } - }, - "/apps/annotations/{annotation_id}": { - "put": { - "summary": "更新标注", - "description": "更新一个已存在的标注。", - "operationId": "updateAnnotation", - "tags": ["标注管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParam" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" } } } - }, - "responses": { - "200": { "description": "标注更新成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } } - } - }, - "delete": { - "summary": "删除标注", - "description": "删除一个标注。", - "operationId": "deleteAnnotation", - "tags": ["标注管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParam" } ], - "responses": { "204": { "description": "标注删除成功，无内容返回。" } } - } - }, - "/apps/annotation-reply/{action}": { - "post": { - "summary": "标注回复初始设置", - "description": "启用或禁用标注回复设置，并配置嵌入模型。此接口异步执行。嵌入模型的提供商和模型名称可通过 v1/workspaces/current/models/model-types/text-embedding 接口获取（使用 Dataset API Token 鉴权）。", - "operationId": "initialAnnotationReplySettings", - "tags": ["标注管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationActionPathParam" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" } } } - }, - "responses": { - "200": { "description": "标注回复设置任务已启动。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, - "202": { "description": "标注回复设置任务已接受。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } } - } - } - }, - "/apps/annotation-reply/{action}/status/{job_id}": { - "get": { - "summary": "查询标注回复初始设置任务状态", - "description": "查询异步执行的标注回复初始设置任务的状态。", - "operationId": "getInitialAnnotationReplySettingsStatus", - "tags": ["标注管理"], - "parameters": [ - { "$ref": "#/components/parameters/AnnotationActionPathParam" }, - { "$ref": "#/components/parameters/JobIdPathParam" } - ], - "responses": { - "200": { "description": "成功获取任务状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobStatusResponse" } } } } - } - } } }, "components": { @@ -441,108 +1227,231 @@ "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", - "description": "API-Key 鉴权。所有 API 请求都应在 `Authorization` HTTP Header 中包含你的 API-Key，格式为 `Bearer {API_KEY}`。**强烈建议开发者把 API-Key 放在后端存储，而非分享或者放在客户端存储，以免 API-Key 泄露，导致财产损失。**" + "description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**" } }, - "parameters": { - "PageQueryParam": { "name": "page", "in": "query", "description": "（可选）分页页码，默认：1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamDefault20": { "name": "limit", "in": "query", "description": "（可选）每页记录数，默认：20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamAnnotation": { "name": "limit", "in": "query", "description": "每页数量，默认 20，范围 1-100。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "AnnotationIdPathParam": { "name": "annotation_id", "in": "path", "required": true, "description": "标注 ID。", "schema": { "type": "string", "format": "uuid" } }, - "AnnotationActionPathParam": { "name": "action", "in": "path", "required": true, "description": "动作，只能是 'enable' 或 'disable'。", "schema": { "type": "string", "enum": ["enable", "disable"] } }, - "JobIdPathParam": { "name": "job_id", "in": "path", "required": true, "description": "任务 ID，从标注回复初始设置接口返回。", "schema": { "type": "string", "format": "uuid" } } - }, "responses": { - "BadRequestCompletion": { "description": "错误的请求。可能原因：`invalid_param`（参数异常），`app_unavailable`（App 配置不可用），`provider_not_initialize`（无可用模型凭据），`provider_quota_exceeded`（额度不足），`model_currently_not_support`（模型不可用），`completion_request_error`（文本生成失败）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "BadRequestFile": { "description": "文件操作相关的错误请求。可能原因：`no_file_uploaded`，`too_many_files`，`unsupported_preview`，`unsupported_estimate`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "ConversationNotFound": { "description": "对话不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "FileTooLarge": { "description": "文件太大 (`file_too_large`)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "UnsupportedFileTypeFile": { "description": "不支持的文件类型 (`unsupported_file_type`)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "S3ErrorFile": { "description": "S3 存储服务错误。可能原因：`s3_connection_failed`，`s3_permission_denied`，`s3_file_too_large`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "InternalServerError": { "description": "服务内部异常。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "SuccessResult": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } } + "SuccessResult": { + "description": "操作成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "结果状态。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { "CompletionRequest": { "type": "object", - "required": ["inputs", "response_mode", "user"], + "required": [ + "inputs", + "user" + ], "properties": { "inputs": { "type": "object", - "description": "（选填）允许传入 App 定义的各变量值。inputs 参数包含了多组键值对，每组的键对应一个特定变量，值则是该变量的具体值。文本生成型应用要求至少传入一组键值对。", - "required": ["query"], - "properties": { - "query": { "type": "string", "description": "用户输入的文本内容。" } - }, - "additionalProperties": true + "description": "允许输入应用定义的各种变量值。包含键值对，每个键对应一个特定变量，每个值为该变量的具体值。请参阅 [获取应用参数](/api-reference/应用配置/获取应用参数) 响应中的 `user_input_form` 字段，以了解应用所需的变量名称和类型。", + "additionalProperties": true + }, + "query": { + "type": "string", + "default": "", + "description": "要处理的输入文本。这是一个旧版参数；在较新的应用中，查询内容应通过 `inputs` 对象传递。" + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "响应返回模式。`streaming`（推荐）使用 SSE。`blocking` 等待完成后返回（长时间处理可能会被中断）。Cloudflare 超时为 `100 s`。省略时默认为阻塞模式。" + }, + "user": { + "type": "string", + "description": "用户标识符，在应用内唯一。此标识符限定数据访问范围——消息和文件仅在使用相同 `user` 值查询时可见。" }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "description": "响应返回模式。`streaming`：流式模式（推荐），基于 SSE 实现打字机输出。`blocking`：阻塞模式，等待执行完毕后返回（长流程可能中断）。Cloudflare 限制为 100 秒超时。" }, - "user": { "type": "string", "description": "用户标识，用于定义终端用户的身份，方便检索、统计。由开发者定义规则，需保证用户标识在应用内唯一。" }, "files": { "type": "array", - "items": { "$ref": "#/components/schemas/InputFileObject" }, - "description": "上传的文件列表（目前仅支持图片）。" + "items": { + "$ref": "#/components/schemas/InputFileObject" + }, + "description": "用于多模态理解的文件列表，包括图片、文档、音频和视频。要附加本地文件，请先通过 [上传文件](/api-reference/文件操作/上传文件) 上传，然后将返回的 `id` 作为 `upload_file_id`，并设置 `transfer_method: local_file`。" } } }, "InputFileObject": { "type": "object", - "required": ["type", "transfer_method"], + "required": [ + "type", + "transfer_method" + ], "properties": { - "type": { "type": "string", "enum": ["image"], "description": "支持类型：图片 `image`。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "传递方式，remote_url 用于图片 URL / local_file 用于文件上传" }, - "url": { "type": "string", "format": "url", "description": "图片地址（当传递方式为 remote_url 时）" }, - "upload_file_id": { "type": "string", "description": "上传文件 ID，必须通过事先上传文件接口获得（当传递方式为 local_file 时）" } + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "文件类型。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件 URL（当 `transfer_method` 为 `remote_url` 时）。" + }, + "upload_file_id": { + "type": "string", + "description": "已上传文件 ID，通过 [上传文件](/api-reference/文件操作/上传文件) API 预先上传获取（当 `transfer_method` 为 `local_file` 时使用）。" + } }, "anyOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } + "properties": { + "transfer_method": { + "enum": [ + "remote_url" + ] + }, + "url": { + "type": "string", + "format": "url" + } }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "required": [ + "url" + ], + "not": { + "required": [ + "upload_file_id" + ] + } }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } + "properties": { + "transfer_method": { + "enum": [ + "local_file" + ] + }, + "upload_file_id": { + "type": "string" + } }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "required": [ + "upload_file_id" + ], + "not": { + "required": [ + "url" + ] + } } ] }, - "ChatCompletionResponse": { + "CompletionResponse": { "type": "object", - "description": "阻塞模式下的完整 App 结果。", "properties": { - "message_id": { "type": "string", "format": "uuid", "description": "消息唯一 ID。" }, - "mode": { "type": "string", "description": "App 模式，固定为 `chat`。", "example": "chat" }, - "answer": { "type": "string", "description": "完整回复内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadata" }, - "created_at": { "type": "integer", "format": "int64", "description": "消息创建时间戳，如：1705395332。" } + "event": { + "type": "string", + "description": "事件类型，固定为 `message`。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "用于请求追踪和 [停止响应](/api-reference/文本生成/停止响应) API 的任务 ID。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "该响应事件的唯一 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯一的消息 ID。调用反馈或推荐问题接口时，将此值作为 `message_id` 参数使用。" + }, + "mode": { + "type": "string", + "description": "应用模式，固定为 `completion`。" + }, + "answer": { + "type": "string", + "description": "完整的响应内容。" + }, + "metadata": { + "type": "object", + "description": "包含用量和检索资源的元数据。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用的检索资源列表。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "消息创建时间戳（Unix 纪元秒）。" + } } }, - "ResponseMetadata": { - "type": "object", "description": "元数据。", - "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, - "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResource" }, "description": "引用和归属分段列表。" } - } - }, - "ChunkEvent": { + "ChunkCompletionEvent": { "type": "object", - "description": "流式响应中的事件块结构。", - "required": ["event"], "properties": { - "event": { "type": "string", "enum": ["message", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], "description": "事件类型。" } + "event": { + "type": "string", + "enum": [ + "message", + "message_end", + "message_file", + "tts_message", + "tts_message_end", + "message_replace", + "error", + "ping" + ], + "description": "流式事件的类型。" + } }, "discriminator": { "propertyName": "event", "mapping": { "message": "#/components/schemas/StreamEventMessage", "message_end": "#/components/schemas/StreamEventMessageEnd", + "message_file": "#/components/schemas/StreamEventMessageFile", "tts_message": "#/components/schemas/StreamEventTtsMessage", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", "message_replace": "#/components/schemas/StreamEventMessageReplace", @@ -552,168 +1461,1081 @@ } }, "StreamEventBase": { - "type": "object", - "properties": { - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID，用于请求跟踪和停止响应接口。" }, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯一 ID。" }, - "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳，如：1705395332。" } + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "任务 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯一消息 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" } + } }, "StreamEventMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "LLM 返回文本块事件。", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLM 返回文本块内容。" } } } + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "LLM 返回文本块事件。", + "properties": { + "answer": { + "type": "string", + "description": "LLM 返回的文本块内容。" + } + } + } ] }, "StreamEventMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "消息结束事件。", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } } } + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息结束事件，收到此事件表示流式输出已结束。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "消息的唯一 ID。" + }, + "metadata": { + "type": "object", + "description": "包含用量和检索资源的元数据。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "使用的检索资源列表。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } ] }, "StreamEventTtsMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "TTS 音频流事件 (Mp3格式, Base64编码)。开启自动播放时可用。", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 编码的音频块。" } } } + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流事件（base64 编码的 MP3）。在启用自动播放时可用。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。" + } + } + } ] }, "StreamEventTtsMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "TTS 音频流结束事件。", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空字符串。" } } } + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流结束事件。", + "properties": { + "audio": { + "type": "string", + "description": "空字符串。标识音频流结束。" + } + } + } + ] + }, + "StreamEventMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "消息文件事件，由工具创建的新文件。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "文件唯一 ID。" + }, + "type": { + "type": "string", + "description": "文件类型，例如 `image`。" + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "该文件的归属方，此处始终为 `assistant`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件的远程 URL。" + } + } + } ] }, "StreamEventMessageReplace": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "消息内容替换事件（内容审查触发）。", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "替换内容（直接替换所有 LLM 回复）。" } } } + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息内容替换事件（例如由于内容审核）。", + "properties": { + "answer": { + "type": "string", + "description": "替换内容。" + }, + "reason": { + "type": "string", + "description": "内容替换的原因。" + } + } + } ] }, "StreamEventError": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "流式输出过程中的异常事件。", "required": ["status", "code", "message"], - "properties": { "status": { "type": "integer", "description": "HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "流式输出过程中的错误事件。", + "properties": { + "status": { + "type": "integer", + "description": "HTTP 状态码。" + }, + "code": { + "type": "string", + "description": "错误码。" + }, + "message": { + "type": "string", + "description": "错误信息。" + } + } } ] }, "StreamEventPing": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "type": "object", "description": "每 10s 一次的 ping 事件，保持连接存活。" } ] + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "Ping 事件，用于保持连接活跃。" + } + ] }, "Usage": { - "type": "object", "description": "模型用量信息。", - "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } + "type": "object", + "properties": { + "prompt_tokens": { + "type": "integer", + "description": "提示词中的令牌数。" + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "每个提示词令牌的单价。" + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "提示词令牌的价格单位。" + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "提示词令牌的总价。" + }, + "completion_tokens": { + "type": "integer", + "description": "补全内容中的令牌数。" + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "每个补全令牌的单价。" + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "补全令牌的价格单位。" + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "补全令牌的总价。" + }, + "total_tokens": { + "type": "integer", + "description": "使用的令牌总数。" + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "所有令牌的总价。" + }, + "currency": { + "type": "string", + "description": "计价货币。" + }, + "latency": { + "type": "number", + "format": "double", + "description": "延迟时间（秒）。" + } + } }, "RetrieverResource": { - "type": "object", "description": "引用和归属分段信息。", - "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "检索资源的唯一 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "该资源所属消息的 ID。" + }, + "position": { + "type": "integer", + "description": "资源在列表中的位置。" + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "知识库 ID。" + }, + "dataset_name": { + "type": "string", + "description": "知识库名称。" + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "文档 ID。" + }, + "document_name": { + "type": "string", + "description": "文档名称。" + }, + "data_source_type": { + "type": "string", + "description": "数据源类型。" + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "文档中特定块的 ID。" + }, + "score": { + "type": "number", + "format": "float", + "description": "资源的相关性评分。" + }, + "hit_count": { + "type": "integer", + "description": "该块被命中的次数。" + }, + "word_count": { + "type": "integer", + "description": "块的字数。" + }, + "segment_position": { + "type": "integer", + "description": "块在文档中的位置。" + }, + "index_node_hash": { + "type": "string", + "description": "索引节点的哈希值。" + }, + "content": { + "type": "string", + "description": "资源的内容片段。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "块内容的摘要。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳（Unix 纪元秒）。" + } + } }, "FileUploadResponse": { - "type": "object", "description": "文件上传成功后的响应。", - "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件大小（byte）。" }, "extension": { "type": "string", "description": "文件后缀。" }, "mime_type": { "type": "string", "description": "文件 mime-type。" }, "created_by": { "type": "string", "format": "uuid", "description": "上传人 ID (示例中为integer，规范为uuid)。" }, "created_at": { "type": "integer", "format": "int64", "description": "上传时间。" } } + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "唯一文件 ID。" + }, + "name": { + "type": "string", + "description": "文件名。" + }, + "size": { + "type": "integer", + "description": "文件大小（字节）。" + }, + "extension": { + "type": "string", + "nullable": true, + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "文件的 MIME 类型。" + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "上传文件的用户 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "上传时间戳（Unix 纪元秒）。" + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "文件的预览 URL。" + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "文件的源 URL。" + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "文件的原始 URL。" + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的用户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的租户 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的会话 ID。" + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "文件的存储键。" + } + } }, "EndUserDetail": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "终端用户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "租户 ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "应用 ID。" + }, + "type": { + "type": "string", + "description": "终端用户类型。Service API 用户固定为 `service_api`。" + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "API 请求中提供的 `user` 标识符（例如 [发送消息](/api-reference/文本生成/发送消息) 中的 `user` 字段）。" + }, + "name": { + "type": "string", + "nullable": true, + "description": "终端用户名称。" + }, + "is_anonymous": { + "type": "boolean", + "description": "用户是否为匿名用户。当原始 API 请求中未提供 `user` 标识符时，值为 `true`。" + }, + "session_id": { + "type": "string", + "description": "会话标识符。默认为 `external_user_id` 的值。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最后更新时间戳。" + } } }, "MessageFeedbackRequest": { - "type": "object", "required": ["user"], "description": "消息反馈请求体。", - "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "点赞 `like`, 点踩 `dislike`, 撤销 `null`。" }, "user": { "type": "string", "description": "用户标识，应用内唯一。" }, "content": { "type": "string", "nullable": true, "description": "消息反馈的具体信息。" } } - }, - "AppFeedbacksResponse": { - "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItem" }, "description": "应用反馈列表。" } } - }, - "FeedbackItem": { - "type": "object", "description": "单个反馈条目。", - "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid", "nullable": true }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string", "nullable": true }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } - }, - "TextToAudioRequest": { - "type": "object", "required": ["user"], "description": "文字转语音请求体。", - "properties": { "message_id": { "type": "string", "format": "uuid", "description": "Dify 生成的消息 ID（优先使用）。" }, "text": { "type": "string", "description": "语音生成内容（若无 message_id）。" }, "user": { "type": "string", "description": "用户标识，应用内唯一。" }, "streaming": {"type": "boolean", "default": false, "description": "是否流式返回音频。"} }, - "example": { "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "text": "你好Dify", "user": "abc-123", "streaming": false } - }, - "AppInfoResponse": { - "type": "object", "description": "应用基本信息。", - "properties": { "name": { "type": "string", "description": "应用名称。" }, "description": { "type": "string", "description": "应用描述。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "应用标签。" } } - }, - "AppParametersResponseCompletion": { - "type": "object", "description": "应用参数信息。", + "type": "object", + "description": "提交消息反馈的请求体。", + "required": [ + "user" + ], "properties": { - "opening_statement": { "type": "string", "description": "开场白。", "example": "nice to meet you" }, - "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "开场推荐问题列表。" }, - "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启回答后推荐问题。" } } }, - "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启语音转文本。" } } }, - "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启引用和归属。" } } }, - "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否开启标记回复。" } } }, - "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItem" }, "description": "用户输入表单配置。" }, - "file_upload": { "$ref": "#/components/schemas/FileUploadSetting" }, - "system_parameters": { "$ref": "#/components/schemas/SystemParameters" } + "rating": { + "type": "string", + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "反馈评分。设为 `null` 可撤销之前提交的反馈。" + }, + "user": { + "type": "string", + "description": "用户标识符，由开发者定义，必须确保在应用内唯一。" + }, + "content": { + "type": "string", + "description": "提供额外详情的可选文字反馈。" + } } }, - "UserInputFormItem": { "type": "object", "description": "用户输入表单中的一个控件。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapper" }, { "$ref": "#/components/schemas/ParagraphControlWrapper" }, { "$ref": "#/components/schemas/SelectControlWrapper" } ] }, - "TextInputControlWrapper": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } }, "required":["text-input"] }, - "ParagraphControlWrapper": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } }, "required":["paragraph"] }, - "SelectControlWrapper": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } }, "required":["select"] }, - "TextInputControl": { "type": "object", "description": "文本输入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "description": "默认值。" }, "max_length": {"type": "integer", "description": "最大长度 (来自示例)。", "nullable": true} } }, - "ParagraphControl": { "type": "object", "description": "段落文本输入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "description": "默认值。" } } }, - "SelectControl": { "type": "object", "description": "下拉控件。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "description": "默认值。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "选项值。" } } }, - "FileUploadSetting": { - "type": "object", "description": "文件上传配置。", - "properties": { "image": { "type": "object", "description": "图片设置。当前仅支持图片类型：`png`, `jpg`, `jpeg`, `webp`, `gif`。", "properties": { "enabled": { "type": "boolean", "description": "是否开启。" }, "number_limits": { "type": "integer", "description": "图片数量限制，默认 3。" }, "detail": {"type": "string", "description": "图片细节 (来自示例)。", "nullable": true}, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] }, "description": "传递方式列表，remote_url , local_file，必选一个。" } } } } + "AppFeedbacksResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "反馈项列表。", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } + } + } }, - "SystemParameters": { - "type": "object", "description": "系统参数。", - "properties": { "file_size_limit": { "type": "integer", "description": "文档上传大小限制 (MB)。" }, "image_file_size_limit": { "type": "integer", "description": "图片文件上传大小限制（MB）。" }, "audio_file_size_limit": { "type": "integer", "description": "音频文件上传大小限制 (MB)。" }, "video_file_size_limit": { "type": "integer", "description": "视频文件上传大小限制 (MB)。" } } + "FeedbackItem": { + "type": "object", + "description": "单条反馈项。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "反馈 ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "应用 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "会话 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。" + }, + "rating": { + "type": "string", + "description": "反馈评分。`like` 为正面，`dislike` 为负面。" + }, + "content": { + "type": "string", + "nullable": true, + "description": "可选的文字反馈。" + }, + "from_source": { + "type": "string", + "description": "反馈来源。`user` 为终端用户通过 API 提交的反馈，`admin` 为从控制台提交的反馈。" + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "提交反馈的终端用户 ID。当 `from_source` 为 `user` 时存在。" + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "提交反馈的账户 ID。当 `from_source` 为 `admin` 时存在。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最后更新时间戳。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "语音转文字的请求体。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音频文件。支持格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。大小限制：`30 MB`。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "语音识别输出的文字。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "文字转语音的请求体。提供 `message_id` 或 `text` 其中之一。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。当同时提供 `text` 时，优先使用消息 ID。" + }, + "text": { + "type": "string", + "description": "要转换的语音内容。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + }, + "voice": { + "type": "string", + "description": "文字转语音使用的声音。可用声音取决于为此应用配置的 TTS 提供商。使用[获取应用参数](/api-reference/应用配置/获取应用参数) → `text_to_speech.voice` 中的 `voice` 值作为默认值。" + }, + "streaming": { + "type": "boolean", + "description": "是否启用流式响应。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "应用名称。" + }, + "description": { + "type": "string", + "description": "应用描述。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "应用标签。" + }, + "mode": { + "type": "string", + "description": "应用模式。`completion` 为文本生成应用，`chat` 为基础对话应用，`agent-chat` 为 Agent 应用，`advanced-chat` 为对话流应用，`workflow` 为工作流应用。" + }, + "author_name": { + "type": "string", + "description": "应用作者名称。" + } + } + }, + "CompletionAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "开始时显示的开场白。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议的初始问题列表。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答后建议问题的配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "语音转文字配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "文字转语音配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + }, + "voice": { + "type": "string", + "description": "TTS 的声音标识符。" + }, + "language": { + "type": "string", + "description": "TTS 的语言。" + }, + "autoPlay": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "自动播放设置。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "检索资源配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "标注回复配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "更多类似内容配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "敏感词过滤配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "user_input_form": { + "type": "array", + "description": "用户输入表单元素列表。", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "文件上传配置。", + "properties": { + "image": { + "type": "object", + "description": "图片上传设置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用图片上传。" + }, + "number_limits": { + "type": "integer", + "description": "最大图片数量。" + }, + "detail": { + "type": "string", + "description": "图片精细程度。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ] + }, + "description": "允许的传输方式。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "系统级参数和限制。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "最大文件大小（MB）。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最大图片文件大小（MB）。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最大音频文件大小（MB）。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最大视频文件大小（MB）。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "工作流文件上传的最大文件数。" + } + } + } + } + }, + "UserInputFormItem": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } + ] + }, + "TextInputControlWrapper": { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } + }, + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } + }, + "SelectControlWrapper": { + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } + }, + "TextInputControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "表单字段的显示标签。" + }, + "variable": { + "type": "string", + "description": "用作 `inputs` 对象中键的变量名。" + }, + "required": { + "type": "boolean", + "description": "提交前是否必须填写此字段。" + }, + "default": { + "type": "string", + "description": "表单字段中预填的默认值。" + } + } + }, + "ParagraphControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "表单字段的显示标签。" + }, + "variable": { + "type": "string", + "description": "用作 `inputs` 对象中键的变量名。" + }, + "required": { + "type": "boolean", + "description": "提交前是否必须填写此字段。" + }, + "default": { + "type": "string", + "description": "表单字段中预填的默认值。" + } + } + }, + "SelectControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "表单字段的显示标签。" + }, + "variable": { + "type": "string", + "description": "用作 `inputs` 对象中键的变量名。" + }, + "required": { + "type": "boolean", + "description": "提交前是否必须做出选择。" + }, + "default": { + "type": "string", + "description": "默认选中的值。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "此表单控件的可选值列表。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "图标的 URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "工具图标。键为工具名称。" + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "使用 emoji 的工具图标详情。", + "properties": { + "background": { + "type": "string", + "description": "十六进制格式的背景颜色。" + }, + "content": { + "type": "string", + "description": "Emoji 内容。" + } + } }, "WebAppSettingsResponse": { - "type": "object", "description": "应用的 WebApp 设置。", - "properties": { "title": { "type": "string", "description": "WebApp 名称。" }, "chat_color_theme": { "type": "string", "description": "聊天颜色主题, hex 格式。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "聊天颜色主题是否反转。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "图标类型, `emoji`-表情, `image`-图片。" }, "icon": { "type": "string", "description": "图标, emoji 或图片 URL。" }, "icon_background": { "type": "string", "description": "hex 格式的背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "图标 URL。" }, "description": { "type": "string", "description": "描述。" }, "copyright": { "type": "string", "description": "版权信息。" }, "privacy_policy": { "type": "string", "description": "隐私政策链接。" }, "custom_disclaimer": { "type": "string", "description": "自定义免责声明。" }, "default_language": { "type": "string", "description": "默认语言。" }, "show_workflow_steps": { "type": "boolean", "description": "是否显示工作流详情。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "是否使用 WebApp 图标替换聊天中的 机器人图标。" } } - }, - "AnnotationListResponse": { - "type": "object", "description": "标注列表响应。", - "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItem" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } - }, - "AnnotationItem": { - "type": "object", "description": "单个标注条目。", - "properties": { "id": { "type": "string", "format": "uuid" }, "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" }, "hit_count": { "type": "integer", "description": "命中次数。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" } } - }, - "CreateAnnotationRequest": { - "type": "object", "required": ["question", "answer"], "description": "创建标注请求体。", - "properties": { "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" } } - }, - "UpdateAnnotationRequest": { - "type": "object", "required": ["question", "answer"], "description": "更新标注请求体。", - "properties": { "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" } } - }, - "InitialAnnotationReplySettingsRequest": { - "type": "object", "required": ["score_threshold"], "description": "标注回复初始设置请求体。", - "properties": { "embedding_provider_name": { "type": "string", "nullable": true, "description": "（可选）指定的嵌入模型提供商名称。" }, "embedding_model_name": { "type": "string", "nullable": true, "description": "（可选）指定的嵌入模型名称。" }, "score_threshold": { "type": "number", "format": "float", "description": "相似度阈值。" } } - }, - "AsyncJobResponse": { - "type": "object", "description": "异步任务响应。", - "properties": { "job_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "job_status": { "type": "string", "description": "任务状态。" } } - }, - "AsyncJobStatusResponse": { - "allOf": [ { "$ref": "#/components/schemas/AsyncJobResponse" }, { "type": "object", "properties": { "error_msg": { "type": "string", "nullable": true, "description": "错误信息（如果任务失败）。" } } } ] - }, - "ErrorResponse": { - "type": "object", "description": "错误响应结构。", - "properties": { "status": { "type": "integer", "description": "HTTP 状态码。", "nullable": true }, "code": { "type": "string", "description": "错误码。", "nullable": true }, "message": { "type": "string", "description": "错误消息。" } } + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp 标题。" + }, + "chat_color_theme": { + "type": "string", + "description": "聊天主题颜色。" + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "聊天主题颜色是否反转。" + }, + "icon_type": { + "type": "string", + "description": "使用的图标类型。`emoji` 为表情图标，`image` 为上传的图片图标。" + }, + "icon": { + "type": "string", + "description": "图标内容（表情或图片 ID）。" + }, + "icon_background": { + "type": "string", + "description": "图标背景颜色。" + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "图标图片的 URL。" + }, + "description": { + "type": "string", + "description": "WebApp 描述。" + }, + "copyright": { + "type": "string", + "description": "版权文本。" + }, + "privacy_policy": { + "type": "string", + "description": "隐私政策 URL。" + }, + "custom_disclaimer": { + "type": "string", + "description": "自定义免责声明文本。" + }, + "default_language": { + "type": "string", + "description": "默认语言代码。" + }, + "show_workflow_steps": { + "type": "boolean", + "description": "是否显示工作流步骤。" + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "是否使用应用图标作为回答图标。" + } + } } } }, "tags": [ - { "name": "文本生成", "description": "与文本生成和完成相关的操作。" }, - { "name": "文件管理", "description": "与文件上传和管理相关的操作。" }, - { "name": "终端用户", "description": "终端用户信息相关的操作。" }, - { "name": "反馈", "description": "与用户反馈相关的操作。" }, - { "name": "语音服务", "description": "与文本转语音相关的操作。" }, - { "name": "应用设置", "description": "获取应用基本信息和参数配置的操作。" }, - { "name": "标注管理", "description": "与标注（用于直接回复）相关的操作。" } + { + "name": "文本生成", + "description": "文本生成相关操作。" + }, + { + "name": "文件操作", + "description": "文件管理相关操作。" + }, + { + "name": "终端用户", + "description": "终端用户信息相关操作。" + }, + { + "name": "消息反馈", + "description": "用户反馈相关操作。" + }, + { + "name": "语音与文字转换", + "description": "语音转文字和文字转语音相关操作。" + }, + { + "name": "应用配置", + "description": "获取应用设置和信息的操作。" + } ] -} \ No newline at end of file +} diff --git a/zh/api-reference/openapi_knowledge.json b/zh/api-reference/openapi_knowledge.json index 0c1e92e6..2473cdd6 100644 --- a/zh/api-reference/openapi_knowledge.json +++ b/zh/api-reference/openapi_knowledge.json @@ -2,13 +2,13 @@ "openapi": "3.0.1", "info": { "title": "知识库 API", - "description": "用于管理知识库（数据集）、文档和段落的 API，包括创建、检索和配置功能。", + "description": "用于管理知识库、文档、分段、元数据和标签的 API，包括创建、检索和配置操作。**注意：**单个知识库 API 密钥有权操作同一账户下所有可见的知识库。请注意数据安全。", "version": "1.0.0" }, "servers": [ { "url": "{apiBaseUrl}", - "description": "知识库 API 的基础 URL。", + "description": "Knowledge API 的基础 URL。", "variables": { "apiBaseUrl": { "default": "https://api.dify.ai/v1", @@ -24,81 +24,271 @@ ], "tags": [ { - "name": "数据集", - "description": "与管理知识库（数据集）相关的操作。" + "name": "知识库", + "description": "用于管理知识库的操作，包括创建、配置和检索。" }, { "name": "文档", - "description": "用于在数据集中创建、更新和管理文档的操作。" + "description": "用于在知识库中创建、更新和管理文档的操作。" }, { - "name": "文档块", - "description": "用于管理文档块（段落）的操作。" + "name": "分段", + "description": "用于管理分段和子分段的操作。" }, { - "name": "元数据和标签", - "description": "用于管理数据集标签和元数据的操作。" + "name": "元数据", + "description": "用于管理知识库元数据字段和文档元数据值的操作。" + }, + { + "name": "标签", + "description": "用于管理知识库标签和标签绑定的操作。" }, { "name": "模型", - "description": "用于检索可用模型的操作。" + "description": "用于获取可用模型的操作。" + }, + { + "name": "知识流水线", + "description": "用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。" } ], "paths": { "/datasets": { "post": { "tags": [ - "数据集" + "知识库" ], "summary": "创建空知识库", - "description": "使用指定配置创建一个新的空知识库（数据集）。", + "description": "创建新的空知识库。创建后，使用 [从文本创建文档](/api-reference/文档/从文本创建文档) 或 [从文件创建文档](/api-reference/文档/从文件创建文档) 添加文档。", "operationId": "createDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateDatasetRequest" + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "知识库名称。" + }, + "description": { + "type": "string", + "maxLength": 400, + "default": "", + "description": "知识库描述。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。" + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "default": "only_me", + "description": "控制谁可以访问此知识库。`only_me` 仅限创建者，`all_team_members` 授权整个工作区访问，`partial_members` 授权指定成员访问。" + }, + "provider": { + "type": "string", + "enum": [ + "vendor", + "external" + ], + "default": "vendor", + "description": "`vendor` 为内部知识库，`external` 为外部知识库。" + }, + "embedding_model": { + "type": "string", + "description": "嵌入模型名称。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `model` 字段值。" + }, + "embedding_model_provider": { + "type": "string", + "description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "外部知识库 API 连接的 ID。" + }, + "external_knowledge_id": { + "type": "string", + "description": "外部知识库的 ID。" + }, + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "摘要索引配置。", + "properties": { + "enable": { + "type": "boolean", + "description": "是否启用摘要索引。" + }, + "model_name": { + "type": "string", + "description": "用于生成摘要的模型名称。" + }, + "model_provider_name": { + "type": "string", + "description": "摘要生成模型的提供商。" + }, + "summary_prompt": { + "type": "string", + "description": "用于摘要生成的自定义提示词模板。" + } + } + } + } } } } }, "responses": { "200": { - "description": "成功创建数据集。", + "description": "知识库创建成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "产品 API 技术文档", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "description": "`dataset_name_duplicate` : 知识库名称已存在，请修改名称。", + "content": { + "application/json": { + "examples": { + "dataset_name_duplicate": { + "summary": "dataset_name_duplicate", + "value": { + "status": 409, + "code": "dataset_name_duplicate", + "message": "The dataset name already exists. Please modify your dataset name." + } + } + } + } + } } } }, "get": { "tags": [ - "数据集" + "知识库" ], "summary": "获取知识库列表", - "description": "检索知识库列表，支持分页和过滤选项。", + "description": "返回知识库的分页列表。支持按关键词和标签筛选。", "operationId": "listDatasets", "parameters": [ + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "description": "要获取的页码。" + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "每页条目数。" + }, { "name": "keyword", "in": "query", - "description": "按名称过滤数据集的搜索关键词。", "schema": { "type": "string" - } + }, + "description": "按名称筛选的搜索关键词。" + }, + { + "name": "include_all", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "是否包含所有知识库，无论权限如何。" }, { "name": "tag_ids", "in": "query", - "description": "要过滤的标签 ID 列表。数据集必须具有所有指定的标签。", "schema": { "type": "array", "items": { @@ -106,45 +296,104 @@ } }, "style": "form", - "explode": false - }, - { - "name": "page", - "in": "query", - "description": "分页的页码。", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "每页返回的项目数。", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } - }, - { - "name": "include_all", - "in": "query", - "description": "是否包含所有数据集。这仅对工作区所有者有效。", - "schema": { - "type": "boolean", - "default": false - } + "explode": true, + "description": "用于筛选的标签 ID。" } ], "responses": { "200": { - "description": "数据集的分页列表。", + "description": "知识库列表。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "知识库对象数组。", + "items": { + "$ref": "#/components/schemas/Dataset" + } + }, + "has_more": { + "type": "boolean", + "description": "下一页是否还有更多项目。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "匹配条目的总数。" + }, + "page": { + "type": "integer", + "description": "当前页码。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "产品 API 技术文档", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } } } } @@ -155,30 +404,118 @@ "/datasets/{dataset_id}": { "get": { "tags": [ - "数据集" + "知识库" ], "summary": "获取知识库详情", - "description": "通过 ID 获取特定知识库的详细信息。", + "description": "获取指定知识库的详细信息，包括嵌入模型、检索配置和文档统计信息。", "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的唯一标识符。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "responses": { "200": { - "description": "关于数据集的详细信息。", + "description": "知识库详情。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "产品 API 技术文档", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 访问此知识库的权限不足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未找到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } } } } @@ -187,21 +524,21 @@ }, "patch": { "tags": [ - "数据集" + "知识库" ], "summary": "更新知识库", - "description": "更新特定知识库的设置。", + "description": "更新现有知识库的名称、描述、权限或检索设置。仅更新请求体中提供的字段。", "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的唯一标识符。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "requestBody": { @@ -209,49 +546,250 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateDatasetRequest" + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "知识库名称。" + }, + "description": { + "type": "string", + "maxLength": 400, + "description": "知识库描述。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。" + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "description": "控制谁可以访问此知识库。`only_me` 仅限创建者，`all_team_members` 授权整个工作区访问，`partial_members` 授权指定成员访问。" + }, + "embedding_model": { + "type": "string", + "description": "嵌入模型名称。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `model` 字段值。" + }, + "embedding_model_provider": { + "type": "string", + "description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。" + }, + "partial_member_list": { + "type": "array", + "description": "当 `permission` 为 `partial_members` 时有访问权限的团队成员列表。", + "items": { + "type": "object", + "properties": { + "user_id": { + "type": "string", + "description": "要授予访问权限的团队成员 ID。" + } + } + } + }, + "external_retrieval_model": { + "type": "object", + "description": "外部知识库的检索设置。", + "properties": { + "top_k": { + "type": "integer", + "description": "返回的最大结果数。" + }, + "score_threshold": { + "type": "number", + "description": "用于过滤结果的最低相关性分数阈值。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "是否启用分数阈值过滤。" + } + } + }, + "external_knowledge_id": { + "type": "string", + "description": "外部知识库的 ID。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "外部知识库 API 连接的 ID。" + } + } } } } }, "responses": { "200": { - "description": "成功更新数据集详情。", + "description": "知识库更新成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "产品 API 技术文档", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, - "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "403": { + "description": "`forbidden` : 访问此知识库的权限不足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未找到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } }, "delete": { "tags": [ - "数据集" + "知识库" ], "summary": "删除知识库", - "description": "删除知识库及其所有相关文档和数据。", + "description": "永久删除知识库及其所有文档。该知识库不能被任何应用正在使用。", "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "要删除的知识库的唯一标识符。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "responses": { "204": { - "description": "成功删除数据集。" + "description": "Success." + }, + "404": { + "description": "`not_found` : 未找到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "409": { + "description": "`dataset_in_use` : 该知识库正在被一些应用使用。请先从应用中移除后再删除。", + "content": { + "application/json": { + "examples": { + "dataset_in_use": { + "summary": "dataset_in_use", + "value": { + "status": 409, + "code": "dataset_in_use", + "message": "The dataset is being used by some apps. Please remove the dataset from the apps before deleting it." + } + } + } + } + } } } } @@ -262,18 +800,18 @@ "文档" ], "summary": "从文本创建文档", - "description": "直接从文本内容在现有知识库中创建新文档。", + "description": "通过纯文本内容创建文档。文档将异步处理——使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。", "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "要添加文档的知识库 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "requestBody": { @@ -281,18 +819,222 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateDocumentByTextRequest" + "type": "object", + "required": [ + "name", + "text" + ], + "properties": { + "name": { + "type": "string", + "description": "文档名称。" + }, + "text": { + "type": "string", + "description": "文档文本内容。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "description": "向知识库添加首个文档时必填。后续文档如果省略此字段，将继承知识库的索引方式。`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。" + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` 为标准文本分段，`hierarchical_model` 为父子分段结构，`qa_model` 为问答对提取。" + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "用于处理优化的文档语言。" + }, + "process_rule": { + "type": "object", + "description": "分块处理规则。", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "处理模式。`automatic` 使用内置规则，`custom` 允许手动配置，`hierarchical` 启用父子分段结构（配合 `doc_form: hierarchical_model` 使用）。" + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "规则标识符。" + }, + "enabled": { + "type": "boolean", + "description": "该预处理规则是否启用。" + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "用于拆分文本的自定义分隔符。" + }, + "max_tokens": { + "type": "integer", + "description": "每个分段的最大令牌数。" + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "分段之间的令牌重叠数。" + } + } + } + } + } + } + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。" + }, + "embedding_model": { + "type": "string", + "description": "嵌入模型名称。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `model` 字段值。" + }, + "embedding_model_provider": { + "type": "string", + "description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。" + }, + "original_document_id": { + "type": "string", + "description": "用于版本控制的原始文档 ID。" + } + } } } } }, "responses": { "200": { - "description": "文档创建成功，正在被索引。", + "description": "文档创建成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "用于跟踪索引进度的批次 ID。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `invalid_param` : 知识库不存在。/ indexing_technique 为必填项。", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + } } } } @@ -306,18 +1048,18 @@ "文档" ], "summary": "从文件创建文档", - "description": "通过上传文件在现有知识库中创建新文档。", + "description": "通过上传文件创建文档。支持常见文档格式（PDF、TXT、DOCX 等）。处理过程为异步——使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。", "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "要添加文档的知识库 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "requestBody": { @@ -326,16 +1068,19 @@ "multipart/form-data": { "schema": { "type": "object", + "required": [ + "file" + ], "properties": { - "data": { - "type": "string", - "description": "包含文档元数据和处理规则的 JSON 字符串。详情请参见 `CreateDocumentByFileRequestData` 模式。", - "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\":{\"separator\":\"###\", \"max_tokens\":500}}},\"summary_index_setting\":{\"enable\":true,\"model_name\":\"qwen-vl-plus\",\"model_provider_name\":\"langgenius/tongyi/tongyi\",\"summary_prompt\":\"summarize the text\"}}" - }, "file": { "type": "string", "format": "binary", "description": "要上传的文件。" + }, + "data": { + "type": "string", + "description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/api-reference/文档/从文本创建文档) 相同的字段（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } @@ -344,179 +1089,228 @@ }, "responses": { "200": { - "description": "文档创建成功，正在被索引。", + "description": "文档创建成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "用于跟踪索引进度的批次 ID。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } } } } }, "400": { - "$ref": "#/components/responses/FileError" - }, - "413": { - "$ref": "#/components/responses/FileTooLarge" - }, - "415": { - "$ref": "#/components/responses/UnsupportedFileType" - } - } - } - }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { - "post": { - "tags": [ - "文档" - ], - "summary": "用文本更新文档", - "description": "使用文本更新现有文档的内容或设置。", - "operationId": "updateDocumentByText", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "包含文档的知识库 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "要更新的文档 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateDocumentByTextRequest" - } - } - } - }, - "responses": { - "200": { - "description": "文档更新成功。", + "description": "- `no_file_uploaded` : 请上传文件。\n- `too_many_files` : 仅允许上传一个文件。\n- `filename_not_exists_error` : 指定的文件名不存在。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `invalid_param` : 知识库不存在、不支持外部数据集、文件过大、不支持的文件类型或缺少必填字段。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" - } - } - } - } - } - } - }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { - "post": { - "tags": [ - "文档" - ], - "summary": "用文件更新文档", - "description": "通过上传新文件更新现有文档，替换其内容。", - "operationId": "updateDocumentByFile", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "包含文档的知识库 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "要更新的文档 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "string", - "description": "包含可选文档名称和处理规则的 JSON 字符串。请参见 `UpdateDocumentByFileRequestData` 模式。", - "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } }, - "file": { - "type": "string", - "format": "binary", - "description": "要上传的新文件。" + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param (indexing_technique)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + }, + "invalid_param_process_rule": { + "summary": "invalid_param (process_rule)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "process_rule is required." + } } } } } } - }, - "responses": { - "200": { - "description": "文档更新成功。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" - } - } - } - } } } }, - "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "/datasets/{dataset_id}/documents": { "get": { "tags": [ "文档" ], - "summary": "获取文档嵌入状态（进度）", - "description": "检索文档批次的索引状态，显示嵌入和处理的进度。", - "operationId": "getDocumentIndexingStatus", + "summary": "获取知识库的文档列表", + "description": "返回知识库中的文档分页列表。支持按关键词和索引状态进行筛选。", + "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { - "name": "batch", - "in": "path", - "required": true, - "description": "从文档创建端点返回的批次号。", + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "description": "要获取的页码。" + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "每页的项目数量。服务器上限为 `100`。" + }, + { + "name": "keyword", + "in": "query", "schema": { "type": "string" - } + }, + "description": "按文档名称筛选的搜索关键词。" + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "queuing", + "indexing", + "paused", + "error", + "available", + "disabled", + "archived" + ] + }, + "description": "按显示状态筛选。" } ], "responses": { "200": { - "description": "批次中文档的索引状态。", + "description": "文档列表。", "content": { "application/json": { "schema": { @@ -524,9 +1318,94 @@ "properties": { "data": { "type": "array", + "description": "知识库对象数组。", "items": { - "$ref": "#/components/schemas/IndexingStatus" + "$ref": "#/components/schemas/Document" } + }, + "has_more": { + "type": "boolean", + "description": "下一页是否还有更多项目。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "匹配条目的总数。" + }, + "page": { + "type": "integer", + "description": "当前页码。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 知识库未找到。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." } } } @@ -542,33 +1421,32 @@ "文档" ], "summary": "获取文档详情", - "description": "检索单个文档的详细信息，包括其处理规则和状态。", + "description": "获取指定文档的详细信息，包括索引状态、元数据和处理统计信息。", "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "文档 ID." }, { "name": "metadata", "in": "query", - "description": "元数据过滤器：`all` 返回所有元数据，`only` 仅返回自定义元数据，`without` 不返回元数据。", "schema": { "type": "string", "enum": [ @@ -577,16 +1455,281 @@ "without" ], "default": "all" - } + }, + "description": "`all` 返回所有字段（包括元数据）。`only` 仅返回 `id`、`doc_type` 和 `doc_metadata`。`without` 返回除 `doc_metadata` 外的所有字段。" } ], "responses": { "200": { - "description": "关于文档的详细信息。", + "description": "文档详情。响应结构根据 `metadata` 查询参数的不同而变化。当 `metadata` 为 `only` 时，仅返回 `id`、`doc_type` 和 `doc_metadata`。当 `metadata` 为 `without` 时，省略 `doc_type` 和 `doc_metadata`。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentDetail" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "文档标识符。" + }, + "position": { + "type": "integer", + "description": "在知识库中的位置索引。" + }, + "data_source_type": { + "type": "string", + "description": "文档的上传方式。文件上传为 `upload_file`，Notion 导入为 `notion_import`。" + }, + "data_source_info": { + "type": "object", + "description": "原始数据源信息。" + }, + "dataset_process_rule_id": { + "type": "string", + "description": "应用于该文档的处理规则 ID。" + }, + "dataset_process_rule": { + "type": "object", + "description": "知识库级别的处理规则配置。" + }, + "document_process_rule": { + "type": "object", + "description": "文档级别的处理规则配置。" + }, + "name": { + "type": "string", + "description": "文档名称。" + }, + "created_from": { + "type": "string", + "description": "文档来源。通过 API 创建时为 `api`，通过 UI 创建时为 `web`。" + }, + "created_by": { + "type": "string", + "description": "创建该文档的用户 ID。" + }, + "created_at": { + "type": "number", + "description": "文档创建的 Unix 时间戳。" + }, + "tokens": { + "type": "integer", + "description": "文档中的令牌数。" + }, + "indexing_status": { + "type": "string", + "description": "当前索引状态，例如 `waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、`error`、`paused`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "索引失败时的错误消息，否则为 `null`。" + }, + "enabled": { + "type": "boolean", + "description": "该文档是否启用检索。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "文档被禁用的 Unix 时间戳，启用时为 `null`。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "禁用该文档的用户 ID，启用时为 `null`。" + }, + "archived": { + "type": "boolean", + "description": "文档是否已归档。" + }, + "display_status": { + "type": "string", + "description": "适合 UI 显示的索引状态。" + }, + "word_count": { + "type": "integer", + "description": "文档的总字数。" + }, + "hit_count": { + "type": "integer", + "description": "该文档被检索的次数。" + }, + "doc_form": { + "type": "string", + "description": "文档分块模式。`text_model` 表示标准文本，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对。" + }, + "doc_language": { + "type": "string", + "description": "文档内容的语言。" + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "文档类型分类，未设置时为 `null`。" + }, + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识符。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段类型。" + }, + "value": { + "type": "string", + "description": "此文档的元数据字段值。" + } + } + }, + "description": "此文档的自定义元数据键值对。" + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "处理完成的 Unix 时间戳，尚未完成时为 `null`。" + }, + "updated_at": { + "type": "number", + "nullable": true, + "description": "最后更新的 Unix 时间戳，从未更新时为 `null`。" + }, + "indexing_latency": { + "type": "number", + "nullable": true, + "description": "索引耗时（秒），未完成时为 `null`。" + }, + "segment_count": { + "type": "integer", + "description": "文档中的分段数。" + }, + "average_segment_length": { + "type": "number", + "description": "分段的平均字符长度。" + }, + "summary_index_status": { + "type": "string", + "nullable": true, + "description": "摘要索引的状态，未启用摘要索引时为 `null`。" + }, + "need_summary": { + "type": "boolean", + "description": "该文档是否需要生成摘要。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "dataset_process_rule": { + "id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "mode": "custom" + }, + "document_process_rule": { + "mode": "custom", + "rules": { + "pre_processing_rules": [], + "segmentation": { + "separator": "###", + "max_tokens": 500, + "chunk_overlap": 50 + } + } + }, + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_language": "English", + "doc_type": null, + "doc_metadata": [], + "completed_at": 1741267260, + "updated_at": 1741267260, + "indexing_latency": 60.0, + "segment_count": 5, + "average_segment_length": 70.0, + "summary_index_status": null, + "need_summary": false + } + } + } + } + } + }, + "400": { + "description": "`invalid_metadata` : 指定键的元数据值无效。", + "content": { + "application/json": { + "examples": { + "invalid_metadata": { + "summary": "invalid_metadata", + "value": { + "status": 400, + "code": "invalid_metadata", + "message": "Invalid metadata value: {metadata_key}" + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 没有权限。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未找到文档。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } @@ -598,92 +1741,81 @@ "文档" ], "summary": "删除文档", - "description": "从知识库中删除特定文档。", + "description": "从知识库中永久删除文档及其所有分段。", "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "要删除的文档 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "文档 ID." } ], "responses": { "204": { - "description": "成功删除文档。" - } - } - } - }, - "/datasets/{dataset_id}/documents": { - "get": { - "tags": [ - "文档" - ], - "summary": "获取知识库的文档列表", - "description": "检索指定知识库中所有文档的分页列表。", - "operationId": "listDocuments", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "知识库的 ID。", - "schema": { - "type": "string", - "format": "uuid" - } + "description": "Success." }, - { - "name": "keyword", - "in": "query", - "description": "在文档名称中搜索的关键词。", - "schema": { - "type": "string" - } - }, - { - "name": "page", - "in": "query", - "description": "分页的页码。", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "每页返回的项目数。", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } - } - ], - "responses": { - "200": { - "description": "文档的分页列表。", + "400": { + "description": "`document_indexing` : 索引期间无法删除文档。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentListResponse" + "examples": { + "document_indexing": { + "summary": "document_indexing", + "value": { + "status": 400, + "code": "document_indexing", + "message": "Cannot delete document during indexing." + } + } + } + } + } + }, + "403": { + "description": "`archived_document_immutable` : 已归档的文档不可编辑。", + "content": { + "application/json": { + "examples": { + "archived_document_immutable": { + "summary": "archived_document_immutable", + "value": { + "status": 403, + "code": "archived_document_immutable", + "message": "The archived document is not editable." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 文档不存在。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document Not Exists." + } + } } } } @@ -691,39 +1823,689 @@ } } }, - "/datasets/{dataset_id}/documents/status/{action}": { - "patch": { + "/datasets/{dataset_id}/documents/{document_id}/download": { + "get": { "tags": [ "文档" ], - "summary": "更新文档状态", - "description": "执行批量操作以更新一个或多个文档的状态（例如，启用、禁用、归档）。", - "operationId": "batchUpdateDocumentStatus", + "summary": "下载文档", + "description": "获取文档原始上传文件的签名下载 URL。", + "operationId": "downloadDocumentZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { - "name": "action", + "name": "document_id", "in": "path", "required": true, - "description": "对文档执行的操作。", "schema": { "type": "string", - "enum": [ - "enable", - "disable", - "archive", - "un_archive" - ] + "format": "uuid" + }, + "description": "文档 ID." + } + ], + "responses": { + "200": { + "description": "下载 URL 生成成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "用于下载原始上传文件的签名 URL。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600" + } + } + } + } } + }, + "403": { + "description": "`forbidden` : 没有权限访问此文档。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未找到文档。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "get": { + "tags": [ + "文档" + ], + "summary": "获取文档嵌入状态（进度）", + "description": "检查批量文档的索引进度。返回每个文档的当前处理阶段和分段完成计数。请轮询此接口直到 `indexing_status` 变为 `completed` 或 `error`。状态按以下顺序推进：`waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`。", + "operationId": "getDocumentIndexingStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "batch", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "创建文档时返回的批次 ID。" + } + ], + "responses": { + "200": { + "description": "批次中文档的索引状态。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "文档标识符。" + }, + "indexing_status": { + "type": "string", + "description": "当前索引状态：`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed` 或 `error`。" + }, + "processing_started_at": { + "type": "number", + "description": "处理开始的 Unix 时间戳。" + }, + "parsing_completed_at": { + "type": "number", + "description": "解析完成的 Unix 时间戳。" + }, + "cleaning_completed_at": { + "type": "number", + "description": "清洗完成的 Unix 时间戳。" + }, + "splitting_completed_at": { + "type": "number", + "description": "拆分完成的 Unix 时间戳。" + }, + "completed_at": { + "type": "number", + "description": "索引完成的 Unix 时间戳。" + }, + "paused_at": { + "type": "number", + "nullable": true, + "description": "索引暂停的时间戳。未暂停时为 `null`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "索引失败时的错误信息。无错误时为 `null`。" + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "索引停止的时间戳。未停止时为 `null`。" + }, + "completed_segments": { + "type": "integer", + "description": "已索引的分段数。" + }, + "total_segments": { + "type": "integer", + "description": "待索引的分段总数。" + } + } + }, + "description": "索引状态条目列表。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "indexing_status": "completed", + "processing_started_at": 1741267200, + "parsing_completed_at": 1741267200, + "cleaning_completed_at": 1741267200, + "splitting_completed_at": 1741267200, + "completed_at": 1741267200, + "paused_at": null, + "error": null, + "stopped_at": null, + "completed_segments": 5, + "total_segments": 5 + } + ] + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 知识库未找到。/ 文档未找到。", + "content": { + "application/json": { + "examples": { + "dataset_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + }, + "documents_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Documents not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { + "post": { + "tags": [ + "文档" + ], + "summary": "用文本更新文档", + "description": "更新现有文档的文本内容、名称或处理配置。内容变更时将重新触发索引——使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。", + "operationId": "updateDocumentByText", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "文档 ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "文档名称。当提供 `text` 时必填。" + }, + "text": { + "type": "string", + "description": "文档文本内容。" + }, + "process_rule": { + "type": "object", + "description": "分块处理规则。", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "处理模式。`automatic` 使用内置规则，`custom` 允许手动配置，`hierarchical` 启用父子分段结构（配合 `doc_form: hierarchical_model` 使用）。" + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "规则标识符。" + }, + "enabled": { + "type": "boolean", + "description": "该预处理规则是否启用。" + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "用于拆分文本的自定义分隔符。" + }, + "max_tokens": { + "type": "integer", + "description": "每个分段的最大令牌数。" + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "分段之间的令牌重叠数。" + } + } + } + } + } + } + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` 为标准文本分段，`hierarchical_model` 为父子分段结构，`qa_model` 为问答对提取。" + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "用于处理优化的文档语言。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "文档更新成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "用于跟踪索引进度的批次 ID。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `invalid_param` : 知识库不存在，或提供文本时 name 为必填项。", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_name_required": { + "summary": "invalid_param (name required)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "name is required when text is provided." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { + "post": { + "tags": [ + "文档" + ], + "summary": "用文件更新文档", + "description": "通过上传新文件更新现有文档。将重新触发索引——使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。", + "operationId": "updateDocumentByFile", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "文档 ID." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "要上传的文件。" + }, + "data": { + "type": "string", + "description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/api-reference/文档/从文本创建文档) 相同的字段（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "文档更新成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "用于跟踪索引进度的批次 ID。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `too_many_files` : 仅允许上传一个文件。\n- `filename_not_exists_error` : 指定的文件名不存在。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `invalid_param` : 知识库不存在、不支持外部数据集、文件过大或不支持的文件类型。", + "content": { + "application/json": { + "examples": { + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/download-zip": { + "post": { + "tags": [ + "文档" + ], + "summary": "批量下载文档（ZIP）", + "description": "将多个上传文件文档下载为单个 ZIP 压缩包。最多接受 `100` 个文档 ID。", + "operationId": "downloadDocumentsZipZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" } ], "requestBody": { @@ -738,11 +2520,13 @@ "properties": { "document_ids": { "type": "array", - "description": "要执行操作的文档 ID 列表。", + "minItems": 1, + "maxItems": 100, "items": { "type": "string", "format": "uuid" - } + }, + "description": "要包含在 ZIP 压缩包中的文档 ID 数组。" } } } @@ -751,39 +2535,87 @@ }, "responses": { "200": { - "$ref": "#/components/responses/Success" + "description": "包含所请求文档的 ZIP 压缩包。", + "content": { + "application/zip": { + "schema": { + "type": "string", + "format": "binary", + "description": "ZIP 压缩包二进制流。" + } + } + } + }, + "403": { + "description": "`forbidden` : 权限不足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 文档或知识库未找到。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } + } + } + } } } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments": { - "post": { + "/datasets/{dataset_id}/documents/status/{action}": { + "patch": { "tags": [ - "文档块" + "文档" ], - "summary": "向文档添加块", - "description": "向特定文档添加一个或多个新块（段落）。这对于手动添加精心策划的内容很有用。", - "operationId": "createSegments", + "summary": "批量更新文档状态", + "description": "批量启用、禁用、归档或取消归档多个文档。", + "operationId": "batchUpdateDocumentStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { - "name": "document_id", + "name": "action", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", - "format": "uuid" - } + "enum": [ + "enable", + "disable", + "archive", + "un_archive" + ] + }, + "description": "`enable` 启用，`disable` 停用，`archive` 归档，`un_archive` 从归档中恢复。" } ], "requestBody": { @@ -791,18 +2623,266 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateSegmentsRequest" + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "要更新的文档 ID 列表。" + } + } } } } }, "responses": { "200": { - "description": "新创建的段落列表。", + "description": "文档更新成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentListResponse" + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操作结果。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "result": "success" + } + } + } + } + } + }, + "400": { + "description": "`invalid_action` : 无效的操作。", + "content": { + "application/json": { + "examples": { + "invalid_action": { + "summary": "invalid_action", + "value": { + "status": 400, + "code": "invalid_action", + "message": "Invalid action." + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 权限不足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 知识库未找到。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments": { + "post": { + "tags": [ + "分段" + ], + "summary": "向文档添加分段", + "description": "在文档中创建一个或多个分段。每个分段可以包含可选的关键词和答案字段（适用于 QA 模式文档）。", + "operationId": "createSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "文档 ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "segments" + ], + "properties": { + "segments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "分段文本内容。" + }, + "answer": { + "type": "string", + "description": "QA 模式的回答内容。" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "分段的关键词。" + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "附件文件 ID。" + } + } + }, + "description": "要创建的分段对象数组。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "分段创建成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + }, + "description": "已创建的分段列表。" + }, + "doc_form": { + "type": "string", + "description": "该文档使用的分块模式。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model" + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 文档未完成或已禁用。", + "content": { + "application/json": { + "examples": { + "not_found_not_completed": { + "summary": "not_found (not completed)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is not completed." + } + }, + "not_found_disabled": { + "summary": "not_found (disabled)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is disabled." + } + } } } } @@ -811,77 +2891,155 @@ }, "get": { "tags": [ - "文档块" + "分段" ], - "summary": "从文档获取块", - "description": "从特定文档检索块（段落）的分页列表。", + "summary": "从文档获取分段", + "description": "返回文档内分段的分页列表。支持按关键词和状态筛选。", "operationId": "listSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } - }, - { - "name": "keyword", - "in": "query", - "description": "按内容过滤段落的关键词。", - "schema": { - "type": "string" - } - }, - { - "name": "status", - "in": "query", - "description": "按索引状态过滤段落。", - "schema": { - "type": "string", - "example": "completed" - } + }, + "description": "文档 ID." }, { "name": "page", "in": "query", - "description": "分页的页码。", "schema": { "type": "integer", "default": 1 - } + }, + "description": "要获取的页码。" }, { "name": "limit", "in": "query", - "description": "每页返回的项目数。", "schema": { "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } + "default": 20 + }, + "description": "每页的项目数量。服务器上限为 `100`。" + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "按索引状态筛选分段，例如 `completed`、`indexing`、`error`。" + }, + { + "name": "keyword", + "in": "query", + "schema": { + "type": "string" + }, + "description": "搜索关键词。" } ], "responses": { "200": { - "description": "段落的分页列表。", + "description": "分段列表。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentPaginatedResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + }, + "description": "分段列表。" + }, + "doc_form": { + "type": "string", + "description": "该文档使用的分块模式。" + }, + "total": { + "type": "integer", + "description": "匹配的分段总数。" + }, + "has_more": { + "type": "boolean", + "description": "下一页是否还有更多项目。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "page": { + "type": "integer", + "description": "当前页码。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model", + "total": 1, + "has_more": false, + "limit": 20, + "page": 1 + } + } } } } @@ -892,50 +3050,100 @@ "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { "get": { "tags": [ - "文档块" + "分段" ], - "summary": "获取文档中的块详情", - "description": "检索文档中特定块（段落）的详情。", + "summary": "获取文档中的分段详情", + "description": "获取指定分段的详细信息，包括内容、关键词和索引状态。", "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "文档 ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "段落的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "responses": { "200": { - "description": "关于段落的详细信息。", + "description": "分段详情。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "该文档使用的分块模式。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } @@ -944,41 +3152,41 @@ }, "post": { "tags": [ - "文档块" + "分段" ], - "summary": "更新文档中的块", - "description": "更新特定块（段落）的内容、关键词或状态。", + "summary": "更新文档中的分段", + "description": "更新分段的内容、关键词或回答。修改后的分段将重新触发索引。", "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "文档 ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "要更新的段落 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "requestBody": { @@ -986,18 +3194,115 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateSegmentRequest" + "type": "object", + "required": [ + "segment" + ], + "properties": { + "segment": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "分段文本内容。" + }, + "answer": { + "type": "string", + "description": "QA 模式的回答内容。" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "分段的关键词。" + }, + "enabled": { + "type": "boolean", + "description": "分段是否已启用。" + }, + "regenerate_child_chunks": { + "type": "boolean", + "default": false, + "description": "是否重新生成子分段。" + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "附件文件 ID。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "摘要索引的摘要内容。" + } + }, + "description": "要更新的分段数据。" + } + } } } } }, "responses": { "200": { - "description": "更新的段落详情。", + "description": "分段更新成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "该文档使用的分块模式。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } @@ -1006,120 +3311,46 @@ }, "delete": { "tags": [ - "文档块" + "分段" ], - "summary": "删除文档中的块", - "description": "从文档中删除特定块（段落）。", + "summary": "删除文档中的分段", + "description": "从文档中永久删除一个分段。", "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "文档 ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "要删除的段落 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "responses": { "204": { - "description": "成功删除段落。" - } - } - } - }, - "/datasets/{dataset_id}/retrieve": { - "post": { - "tags": [ - "数据集" - ], - "summary": "从知识库检索块 / 测试检索", - "description": "对知识库执行搜索查询以检索最相关的块（段落）。此端点可用于生产检索和测试检索。", - "operationId": "retrieveSegments", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "要检索的知识库 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RetrieveRequest" - } - } - } - }, - "responses": { - "200": { - "description": "与查询匹配的检索段落列表。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RetrieveResponse" - } - } - } - } - } - } - }, - "/workspaces/current/models/model-types/text-embedding": { - "get": { - "tags": [ - "模型" - ], - "summary": "获取可用的嵌入模型", - "description": "获取可用于创建和查询知识库的所有可用文本嵌入模型列表。", - "operationId": "getAvailableEmbeddingModels", - "responses": { - "200": { - "description": "按提供商分组的可用嵌入模型列表。", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ModelProvider" - } - } - } - } - } - } + "description": "Success." } } } @@ -1127,41 +3358,41 @@ "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { "post": { "tags": [ - "文档块" + "分段" ], - "summary": "创建子块", - "description": "使用分层模式在文档中的父段落下创建新的子块。", + "summary": "创建子分段", + "description": "在父分段下创建子分段。仅适用于使用 `hierarchical_model` 分块模式的文档。", "operationId": "createChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "文档 ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "父段落的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "requestBody": { @@ -1169,18 +3400,66 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateChildChunkRequest" + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "子分段文本内容。" + } + } } } } }, "responses": { "200": { - "description": "成功创建子块。", + "description": "子分段创建成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 创建子分段索引失败。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } + } } } } @@ -1189,77 +3468,126 @@ }, "get": { "tags": [ - "文档块" + "分段" ], - "summary": "获取子块", - "description": "检索特定父段落的子块列表。", + "summary": "获取子分段", + "description": "返回特定父分段下子分段的分页列表。", "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "文档 ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "父段落的 ID。", "schema": { "type": "string", "format": "uuid" - } - }, - { - "name": "keyword", - "in": "query", - "description": "过滤子块的搜索关键词。", - "schema": { - "type": "string" - } + }, + "description": "Chunk ID." }, { "name": "page", "in": "query", - "description": "分页的页码。", "schema": { "type": "integer", - "default": 1 - } + "default": 1, + "minimum": 1 + }, + "description": "要获取的页码。" }, { "name": "limit", "in": "query", - "description": "每页返回的项目数。", "schema": { "type": "integer", "default": 20, - "maximum": 100 - } + "minimum": 1 + }, + "description": "每页的项目数量。服务器上限为 `100`。" + }, + { + "name": "keyword", + "in": "query", + "schema": { + "type": "string" + }, + "description": "搜索关键词。" } ], "responses": { "200": { - "description": "子块的分页列表。", + "description": "子分段列表。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChildChunk" + }, + "description": "子分段列表。" + }, + "total": { + "type": "integer", + "description": "子分段总数。" + }, + "total_pages": { + "type": "integer", + "description": "总页数。" + }, + "page": { + "type": "integer", + "description": "当前页码。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + ], + "total": 1, + "total_pages": 1, + "page": 1, + "limit": 20 + } + } } } } @@ -1270,51 +3598,51 @@ "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { "patch": { "tags": [ - "文档块" + "分段" ], - "summary": "更新子块", - "description": "更新特定子块的内容。", + "summary": "更新子分段", + "description": "更新现有子分段的内容。", "operationId": "updateChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "文档 ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "父段落的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." }, { "name": "child_chunk_id", "in": "path", "required": true, - "description": "要更新的子块 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "子分段 ID。" } ], "requestBody": { @@ -1322,18 +3650,66 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateChildChunkRequest" + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "子分段文本内容。" + } + } } } } }, "responses": { "200": { - "description": "成功更新子块。", + "description": "子分段更新成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 更新子分段索引失败。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } + } } } } @@ -1342,56 +3718,543 @@ }, "delete": { "tags": [ - "文档块" + "分段" ], - "summary": "删除子块", - "description": "删除特定的子块。", + "summary": "删除子分段", + "description": "从父分段中永久删除一个子分段。", "operationId": "deleteChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "文档 ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "父段落的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." }, { "name": "child_chunk_id", "in": "path", "required": true, - "description": "要删除的子块 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "子分段 ID。" } ], "responses": { "204": { - "description": "成功删除子块。" + "description": "Success." + }, + "400": { + "description": "`invalid_param` : 删除子分段索引失败。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Delete child chunk index failed: {error details}" + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/retrieve": { + "post": { + "tags": [ + "知识库" + ], + "summary": "从知识库检索分段 / 测试检索", + "description": "对知识库执行搜索查询，检索最相关的分段。此接口可用于生产环境检索和测试检索。", + "operationId": "retrieveSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "maxLength": 250, + "description": "搜索查询文本。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。" + }, + "external_retrieval_model": { + "type": "object", + "description": "外部知识库的检索设置。", + "properties": { + "top_k": { + "type": "integer", + "description": "返回的最大结果数。" + }, + "score_threshold": { + "type": "number", + "description": "用于过滤结果的最低相关性分数阈值。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "是否启用分数阈值过滤。" + } + } + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "要包含在检索上下文中的附件 ID 列表。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "检索结果。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "query": { + "type": "object", + "description": "原始查询对象。", + "properties": { + "content": { + "type": "string", + "description": "查询文本。" + } + } + }, + "records": { + "type": "array", + "items": { + "type": "object", + "properties": { + "segment": { + "type": "object", + "description": "从知识库中匹配的分段。", + "properties": { + "id": { + "type": "string", + "description": "分段的唯一标识符。" + }, + "position": { + "type": "integer", + "description": "分段在文档中的位置。" + }, + "document_id": { + "type": "string", + "description": "该分段所属文档的 ID。" + }, + "content": { + "type": "string", + "description": "分段的文本内容。" + }, + "sign_content": { + "type": "string", + "description": "用于完整性验证的签名内容哈希。" + }, + "answer": { + "type": "string", + "description": "回答内容，用于问答模式文档。" + }, + "word_count": { + "type": "integer", + "description": "分段内容的字数。" + }, + "tokens": { + "type": "integer", + "description": "分段内容的令牌数。" + }, + "keywords": { + "type": "array", + "description": "与该分段关联的关键词，用于基于关键词的检索。", + "items": { + "type": "string" + } + }, + "index_node_id": { + "type": "string", + "description": "向量存储中索引节点的 ID。" + }, + "index_node_hash": { + "type": "string", + "description": "索引内容的哈希值，用于检测变更。" + }, + "hit_count": { + "type": "integer", + "description": "该分段在检索查询中被匹配的次数。" + }, + "enabled": { + "type": "boolean", + "description": "该分段是否启用检索。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "分段被禁用的时间戳。启用时为 `null`。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "禁用该分段的用户 ID。启用时为 `null`。" + }, + "status": { + "type": "string", + "description": "分段的索引状态。" + }, + "created_by": { + "type": "string", + "description": "创建该分段的用户 ID。" + }, + "created_at": { + "type": "number", + "description": "创建时间戳（Unix 纪元，单位为秒）。" + }, + "indexing_at": { + "type": "number", + "nullable": true, + "description": "索引开始的时间戳。尚未开始时为 `null`。" + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "索引完成的时间戳。尚未完成时为 `null`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "索引失败时的错误消息。无错误时为 `null`。" + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "索引停止的时间戳。未停止时为 `null`。" + }, + "document": { + "type": "object", + "description": "匹配分段的父文档信息。", + "properties": { + "id": { + "type": "string", + "description": "文档的唯一标识符。" + }, + "data_source_type": { + "type": "string", + "description": "文档的创建方式。" + }, + "name": { + "type": "string", + "description": "文档名称。" + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "文档类型分类。未设置时为 `null`。" + }, + "doc_metadata": { + "type": "object", + "nullable": true, + "description": "文档的元数据值。未配置元数据时为 `null`。" + } + } + } + } + }, + "child_chunks": { + "type": "array", + "description": "使用分层索引时，分段内匹配的子分段。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "子分段的唯一标识符。" + }, + "content": { + "type": "string", + "description": "子分段的文本内容。" + }, + "position": { + "type": "integer", + "description": "子分段在父分段中的位置。" + }, + "score": { + "type": "number", + "description": "子分段的相关性得分。" + } + } + } + }, + "score": { + "type": "number", + "description": "相关性得分。" + }, + "tsne_position": { + "type": "object", + "nullable": true, + "description": "t-SNE 可视化位置。" + }, + "files": { + "type": "array", + "description": "附加到该分段的文件。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "附件文件标识符。" + }, + "name": { + "type": "string", + "description": "原始文件名。" + }, + "size": { + "type": "integer", + "description": "文件大小（字节）。" + }, + "extension": { + "type": "string", + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "description": "文件的 MIME 类型。" + }, + "source_url": { + "type": "string", + "description": "访问附件的 URL。" + } + } + } + }, + "summary": { + "type": "string", + "nullable": true, + "description": "通过摘要索引检索到的摘要内容。" + } + } + }, + "description": "匹配的检索记录列表。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "query": { + "content": "What is Dify?" + }, + "records": [ + { + "segment": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 1, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "data_source_type": "upload_file", + "name": "guide.txt", + "doc_type": null, + "doc_metadata": null + } + }, + "child_chunks": [], + "score": 0.92, + "tsne_position": null, + "files": [], + "summary": null + } + ] + } + } + } + } + } + }, + "400": { + "description": "- `dataset_not_initialized` : 知识库仍在初始化或索引中。请稍候。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。请前往设置 -> 模型提供商完成凭据配置。\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "dataset_not_initialized": { + "summary": "dataset_not_initialized", + "value": { + "status": 400, + "code": "dataset_not_initialized", + "message": "The dataset is still being initialized or indexing. Please wait a moment." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Invalid parameter value." + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 权限不足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 知识库未找到。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 检索过程中发生内部错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "An internal error occurred." + } + } + } + } + } } } } @@ -1399,10 +4262,10 @@ "/datasets/tags": { "post": { "tags": [ - "元数据和标签" + "标签" ], - "summary": "创建新的知识库类型标签", - "description": "创建可用于分类知识库的新标签。", + "summary": "创建知识库标签", + "description": "创建新标签以组织知识库。", "operationId": "createKnowledgeTag", "requestBody": { "required": true, @@ -1416,8 +4279,9 @@ "properties": { "name": { "type": "string", - "description": "新标签的名称。", - "maxLength": 50 + "minLength": 1, + "maxLength": 50, + "description": "Tag name." } } } @@ -1426,11 +4290,41 @@ }, "responses": { "200": { - "description": "成功创建标签。", + "description": "标签创建成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "标签标识符。" + }, + "name": { + "type": "string", + "description": "标签显示名称。" + }, + "type": { + "type": "string", + "description": "标签类型。知识库标签始终为 `knowledge`。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "绑定到该标签的知识库数量。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } } } } @@ -1439,10 +4333,10 @@ }, "get": { "tags": [ - "元数据和标签" + "标签" ], - "summary": "获取知识库类型标签", - "description": "检索所有可用知识库标签的列表。", + "summary": "获取知识库标签列表", + "description": "返回工作区中所有知识库标签的列表。", "operationId": "getKnowledgeTags", "responses": { "200": { @@ -1452,7 +4346,39 @@ "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "标签标识符。" + }, + "name": { + "type": "string", + "description": "标签显示名称。" + }, + "type": { + "type": "string", + "description": "标签类型。知识库标签始终为 `knowledge`。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "绑定到该标签的知识库数量。" + } + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + ] } } } @@ -1462,10 +4388,10 @@ }, "patch": { "tags": [ - "元数据和标签" + "标签" ], - "summary": "修改知识库类型标签名称", - "description": "更新现有标签的名称。", + "summary": "修改知识库标签", + "description": "重命名现有的知识库标签。", "operationId": "updateKnowledgeTag", "requestBody": { "required": true, @@ -1480,13 +4406,13 @@ "properties": { "tag_id": { "type": "string", - "description": "要修改的标签 ID。", - "format": "uuid" + "description": "要更新的标签 ID。" }, "name": { "type": "string", - "description": "标签的新名称。", - "maxLength": 50 + "minLength": 1, + "maxLength": 50, + "description": "新标签名称。" } } } @@ -1495,11 +4421,41 @@ }, "responses": { "200": { - "description": "成功更新标签。", + "description": "标签更新成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "标签标识符。" + }, + "name": { + "type": "string", + "description": "标签显示名称。" + }, + "type": { + "type": "string", + "description": "标签类型。知识库标签始终为 `knowledge`。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "绑定到该标签的知识库数量。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } } } } @@ -1508,10 +4464,10 @@ }, "delete": { "tags": [ - "元数据和标签" + "标签" ], - "summary": "删除知识库类型标签", - "description": "删除标签。标签不得绑定到任何知识库。", + "summary": "删除知识库标签", + "description": "永久删除知识库标签。不会删除已被标记的知识库。", "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, @@ -1525,8 +4481,7 @@ "properties": { "tag_id": { "type": "string", - "description": "要删除的标签 ID。", - "format": "uuid" + "description": "要删除的标签 ID。" } } } @@ -1534,8 +4489,8 @@ } }, "responses": { - "200": { - "$ref": "#/components/responses/Success" + "204": { + "description": "Success." } } } @@ -1543,10 +4498,10 @@ "/datasets/tags/binding": { "post": { "tags": [ - "元数据和标签" + "标签" ], - "summary": "将数据集绑定到知识库类型标签", - "description": "将一个或多个标签绑定到特定知识库。", + "summary": "绑定标签到知识库", + "description": "将一个或多个标签绑定到知识库。一个知识库可以有多个标签。", "operationId": "bindTagsToDataset", "requestBody": { "required": true, @@ -1555,22 +4510,21 @@ "schema": { "type": "object", "required": [ - "target_id", - "tag_ids" + "tag_ids", + "target_id" ], "properties": { - "target_id": { - "type": "string", - "description": "要绑定标签的数据集 ID。", - "format": "uuid" - }, "tag_ids": { "type": "array", - "description": "要绑定的标签 ID 列表。", "items": { - "type": "string", - "format": "uuid" - } + "type": "string" + }, + "minItems": 1, + "description": "要绑定的标签 ID。" + }, + "target_id": { + "type": "string", + "description": "知识库 ID。" } } } @@ -1578,8 +4532,8 @@ } }, "responses": { - "200": { - "$ref": "#/components/responses/Success" + "204": { + "description": "Success." } } } @@ -1587,10 +4541,10 @@ "/datasets/tags/unbinding": { "post": { "tags": [ - "元数据和标签" + "标签" ], - "summary": "解绑数据集和知识库类型标签", - "description": "从知识库解绑特定标签。", + "summary": "解除标签与知识库的绑定", + "description": "移除知识库的标签绑定。", "operationId": "unbindTagFromDataset", "requestBody": { "required": true, @@ -1599,19 +4553,17 @@ "schema": { "type": "object", "required": [ - "target_id", - "tag_id" + "tag_id", + "target_id" ], "properties": { - "target_id": { - "type": "string", - "description": "数据集的 ID。", - "format": "uuid" - }, "tag_id": { "type": "string", - "description": "要解绑的标签 ID。", - "format": "uuid" + "description": "要解绑的标签 ID。" + }, + "target_id": { + "type": "string", + "description": "知识库 ID。" } } } @@ -1619,8 +4571,8 @@ } }, "responses": { - "200": { - "$ref": "#/components/responses/Success" + "204": { + "description": "Success." } } } @@ -1628,26 +4580,26 @@ "/datasets/{dataset_id}/tags": { "get": { "tags": [ - "元数据和标签" + "标签" ], - "summary": "查询绑定到数据集的标签", - "description": "检索当前绑定到特定数据集的所有标签。", + "summary": "获取知识库绑定的标签", + "description": "返回绑定到特定知识库的标签列表。", "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "数据集的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "responses": { "200": { - "description": "绑定到数据集的标签列表。", + "description": "绑定到知识库的标签。", "content": { "application/json": { "schema": { @@ -1660,16 +4612,1268 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "description": "标签标识符。" }, "name": { - "type": "string" + "type": "string", + "description": "标签显示名称。" + } + } + }, + "description": "绑定到此知识库的标签列表。" + }, + "total": { + "type": "integer", + "description": "绑定到该知识库的标签总数。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs" + } + ], + "total": 1 + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata": { + "post": { + "tags": [ + "元数据" + ], + "summary": "创建元数据字段", + "description": "为知识库创建自定义元数据字段。元数据字段可用于为文档添加结构化信息标注。", + "operationId": "createMetadataFieldZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "string", + "number", + "time" + ], + "description": "`string` 为文本值，`number` 为数值，`time` 为日期/时间值。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "元数据字段创建成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识符。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段类型。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "get": { + "tags": [ + "元数据" + ], + "summary": "获取元数据字段列表", + "description": "返回知识库的所有元数据字段列表（包括自定义和内置字段），以及使用每个字段的文档数量。", + "operationId": "listMetadataFieldsZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "responses": { + "200": { + "description": "知识库的元数据字段。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识符。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段类型。" + }, + "count": { + "type": "integer", + "description": "使用该元数据字段的文档数量。" + } + } + }, + "description": "元数据字段定义列表。" + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "该知识库是否启用了内置元数据字段。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "doc_metadata": [ + { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string", + "count": 3 + } + ], + "built_in_field_enabled": true + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/{metadata_id}": { + "patch": { + "tags": [ + "元数据" + ], + "summary": "更新元数据字段", + "description": "重命名自定义元数据字段。", + "operationId": "updateMetadataFieldZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "元数据字段 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "新元数据字段名称。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "元数据字段更新成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识符。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段类型。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "delete": { + "tags": [ + "元数据" + ], + "summary": "删除元数据字段", + "description": "永久删除自定义元数据字段。使用此字段的文档将丢失其对应的元数据值。", + "operationId": "deleteMetadataFieldZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "元数据字段 ID。" + } + ], + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in": { + "get": { + "tags": [ + "元数据" + ], + "summary": "获取内置元数据字段", + "description": "返回系统提供的内置元数据字段列表（例如文档类型、来源 URL）。", + "operationId": "getBuiltInMetadataFieldsZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "responses": { + "200": { + "description": "内置元数据字段。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "fields": { + "type": "array", + "description": "系统提供的元数据字段列表。", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "内置字段标识符。`document_name` 表示文档标题，`uploader` 表示创建者，`upload_date` 表示创建时间，`last_update_date` 表示最后修改时间，`source` 表示文档来源。" + }, + "type": { + "type": "string", + "description": "字段数据类型。文本值为 `string`，日期/时间值为 `time`。" } } } + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "fields": [ + { + "name": "document_name", + "type": "string" + }, + { + "name": "uploader", + "type": "string" + }, + { + "name": "upload_date", + "type": "time" + }, + { + "name": "last_update_date", + "type": "time" + }, + { + "name": "source", + "type": "string" + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in/{action}": { + "post": { + "tags": [ + "元数据" + ], + "summary": "更新内置元数据字段", + "description": "启用或禁用知识库的内置元数据字段。", + "operationId": "toggleBuiltInMetadataFieldZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + }, + "description": "`enable` 启用内置元数据字段，`disable` 停用内置元数据字段。" + } + ], + "responses": { + "200": { + "description": "内置元数据字段切换成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操作结果。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/metadata": { + "post": { + "tags": [ + "元数据" + ], + "summary": "批量更新文档元数据", + "description": "批量更新多个文档的元数据值。请求中的每个文档将接收指定的元数据键值对。", + "operationId": "batchUpdateDocumentMetadataZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "operation_data" + ], + "properties": { + "operation_data": { + "type": "array", + "items": { + "type": "object", + "required": [ + "document_id", + "metadata_list" + ], + "properties": { + "document_id": { + "type": "string", + "description": "要更新元数据的文档 ID。" + }, + "metadata_list": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { + "type": "string", + "description": "元数据字段 ID。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "value": { + "description": "元数据值。可以是字符串、数字或 `null`。" + } + } + } + }, + "partial_update": { + "type": "boolean", + "default": false, + "description": "是否部分更新元数据，保留未指定字段的现有值。" + } + } }, - "total": { - "type": "integer" + "description": "文档元数据更新操作数组。每个条目将一个文档 ID 映射到其元数据键值对。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "文档元数据更新成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操作结果。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/workspaces/current/models/model-types/{model_type}": { + "get": { + "tags": [ + "模型" + ], + "summary": "获取可用模型", + "description": "按类型获取可用模型列表。主要用于查询知识库配置所需的 `text-embedding` 和 `rerank` 模型。", + "operationId": "getAvailableModelsZh", + "parameters": [ + { + "name": "model_type", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "text-embedding", + "rerank", + "llm", + "tts", + "speech2text", + "moderation" + ] + }, + "description": "要获取的模型类型。对于知识库配置，使用 `text-embedding` 获取嵌入模型，使用 `rerank` 获取重排序模型。" + } + ], + "responses": { + "200": { + "description": "指定类型的可用模型。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "模型提供商及其可用模型的列表。", + "items": { + "type": "object", + "properties": { + "provider": { + "type": "string", + "description": "模型提供商标识符，例如 `openai`、`cohere`。" + }, + "label": { + "type": "object", + "description": "提供商的本地化显示名称。", + "properties": { + "en_US": { + "type": "string", + "description": "英文显示名称。" + }, + "zh_Hans": { + "type": "string", + "description": "中文显示名称。" + } + } + }, + "icon_small": { + "type": "object", + "description": "提供商小图标的 URL。", + "properties": { + "en_US": { + "type": "string", + "description": "小图标 URL。" + } + } + }, + "icon_large": { + "type": "object", + "description": "提供商大图标的 URL。", + "properties": { + "en_US": { + "type": "string", + "description": "大图标 URL。" + } + } + }, + "status": { + "type": "string", + "description": "提供商状态。凭证已配置且有效时为 `active`。" + }, + "models": { + "type": "array", + "description": "该提供商的可用模型列表。", + "items": { + "type": "object", + "properties": { + "model": { + "type": "string", + "description": "模型标识符。创建或更新知识库时，将此值作为 `embedding_model` 参数使用。" + }, + "label": { + "type": "object", + "description": "模型的本地化显示名称。", + "properties": { + "en_US": { + "type": "string", + "description": "英文模型名称。" + }, + "zh_Hans": { + "type": "string", + "description": "中文模型名称。" + } + } + }, + "model_type": { + "type": "string", + "description": "模型类型，与 `model_type` 路径参数匹配。" + }, + "features": { + "type": "array", + "nullable": true, + "description": "模型支持的功能，无功能时为 `null`。", + "items": { + "type": "string" + } + }, + "fetch_from": { + "type": "string", + "description": "模型定义的来源。`predefined-model` 表示内置模型，`customizable-model` 表示用户自配置的模型。" + }, + "model_properties": { + "type": "object", + "description": "模型特定的属性，例如 `context_size`。" + }, + "status": { + "type": "string", + "description": "模型可用状态。就绪时为 `active`。" + } + } + } + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "data": [ + { + "provider": "openai", + "label": { + "en_US": "OpenAI", + "zh_Hans": "OpenAI" + }, + "icon_small": { + "en_US": "https://example.com/openai-small.svg" + }, + "icon_large": { + "en_US": "https://example.com/openai-large.svg" + }, + "status": "active", + "models": [ + { + "model": "text-embedding-3-small", + "label": { + "en_US": "text-embedding-3-small", + "zh_Hans": "text-embedding-3-small" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8191 + }, + "status": "active" + } + ] + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/pipeline/file-upload": { + "post": { + "tags": [ + "知识流水线" + ], + "summary": "上传流水线文件", + "description": "上传文件以在知识流水线中使用。通过 `multipart/form-data` 接受单个文件。", + "operationId": "uploadPipelineFileZh", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "要上传的文件。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "文件上传成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "已上传文件的唯一标识符。" + }, + "name": { + "type": "string", + "description": "原始文件名。" + }, + "size": { + "type": "integer", + "description": "文件大小（字节）。" + }, + "extension": { + "type": "string", + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "description": "文件的 MIME 类型。" + }, + "created_by": { + "type": "string", + "description": "上传文件的用户 ID。" + }, + "created_at": { + "type": "string", + "description": "上传时间戳（ISO 8601 格式）。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "report.pdf", + "size": 524288, + "extension": "pdf", + "mime_type": "application/pdf", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": "2025-03-06T12:00:00" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : 请上传文件。\n- `filename_not_exists_error` : 指定的文件名不存在。\n- `too_many_files` : 仅允许上传一个文件。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : 文件大小超出限制。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 不允许的文件类型。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/datasource-plugins": { + "get": { + "tags": [ + "知识流水线" + ], + "summary": "获取数据源插件列表", + "description": "列出知识流水线可用的所有数据源插件。根据 `is_published` 查询参数返回已发布或草稿状态的插件。", + "operationId": "listDatasourcePluginsZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "is_published", + "in": "query", + "schema": { + "type": "boolean", + "default": true + }, + "description": "获取已发布还是草稿状态的数据源插件。`true` 返回已发布的插件，`false` 返回草稿插件。" + } + ], + "responses": { + "200": { + "description": "数据源插件列表。", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "数据源插件的唯一标识符。" + }, + "name": { + "type": "string", + "description": "数据源插件的显示名称。" + }, + "type": { + "type": "string", + "description": "数据源插件类型。" + } + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": [ + { + "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", + "name": "Web Scraper", + "type": "online_document" + } + ] + } + } + } + } + }, + "404": { + "description": "`not_found` : 未找到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": { + "post": { + "tags": [ + "知识流水线" + ], + "summary": "执行数据源节点", + "description": "在知识流水线中执行单个数据源节点。返回包含节点执行结果的流式响应。", + "operationId": "runDatasourceNodeZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "node_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "要执行的数据源节点 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "is_published" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "数据源节点的输入变量。" + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "数据源类型。" + }, + "credential_id": { + "type": "string", + "nullable": true, + "description": "用于数据源认证的凭证 ID。" + }, + "is_published": { + "type": "boolean", + "description": "运行节点的已发布版本还是草稿版本。`true` 运行已发布版本，`false` 运行草稿版本。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "包含节点执行事件的流式响应。", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "包含节点执行进度和结果的 Server-Sent Events 流。" + } + } + } + }, + "404": { + "description": "`not_found` : 未找到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/run": { + "post": { + "tags": [ + "知识流水线" + ], + "summary": "运行流水线", + "description": "为知识库执行完整的知识流水线。支持流式和阻塞两种响应模式。", + "operationId": "runPipelineZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "datasource_info_list", + "start_node_id", + "is_published", + "response_mode" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "流水线的输入变量。" + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "数据源类型。" + }, + "datasource_info_list": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "供流水线处理的数据源信息对象列表。" + }, + "start_node_id": { + "type": "string", + "description": "流水线开始执行的节点 ID。" + }, + "is_published": { + "type": "boolean", + "description": "运行流水线的已发布版本还是草稿版本。`true` 运行已发布版本，`false` 运行草稿版本。" + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "流水线执行的响应模式。`streaming` 返回服务器发送事件流，`blocking` 等待并返回完整结果。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "流水线执行结果。格式取决于 `response_mode`：流式返回 `text/event-stream`，阻塞返回完整的 JSON 结果。", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "包含流水线执行进度和结果的服务器发送事件流。当 `response_mode` 为 `streaming` 时返回。" + } + }, + "application/json": { + "schema": { + "type": "object", + "description": "完整的流水线执行结果。当 `response_mode` 为 `blocking` 时返回。", + "additionalProperties": true + }, + "examples": { + "success": { + "summary": "Blocking Response Example", + "value": { + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "data": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "status": "succeeded", + "outputs": {}, + "created_at": 1741267200, + "finished_at": 1741267210 + } + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 禁止访问。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未找到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "500": { + "description": "`pipeline_run_error` : 流水线执行失败。", + "content": { + "application/json": { + "examples": { + "pipeline_run_error": { + "summary": "pipeline_run_error", + "value": { + "status": 500, + "code": "pipeline_run_error", + "message": "Pipeline execution failed: connection timeout" } } } @@ -1681,403 +5885,338 @@ } }, "components": { - "securitySchemes": { - "ApiKeyAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "API_KEY", - "description": "API-Key 鉴权。所有 API 请求都应在 `Authorization` HTTP Header 中包含你的 API-Key，格式为 `Bearer {API_KEY}`。**强烈建议开发者把 API-Key 放在后端存储，而非分享或者放在客户端存储，以免 API-Key 泄露，导致财产损失。**" - } - }, - "responses": { - "Success": { - "description": "操作成功。", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" - } - } - } - } - } - }, - "FileError": { - "description": "与文件上传相关的错误请求。可能是 `no_file_uploaded` 或 `too_many_files`。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "FileTooLarge": { - "description": "文件大小超出限制。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "UnsupportedFileType": { - "description": "不允许的文件类型。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "DatasetNameDuplicate": { - "description": "数据集名称已存在。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - }, "schemas": { - "ErrorResponse": { + "Dataset": { "type": "object", - "properties": { - "code": { - "type": "string", - "description": "机器可读的错误代码。" - }, - "message": { - "type": "string", - "description": "人类可读的错误消息。" - }, - "status": { - "type": "integer", - "description": "HTTP 状态码。" - } - }, - "example": { - "code": "no_file_uploaded", - "message": "请上传你的文件。", - "status": 400 - } - }, - "RetrievalModel": { - "type": "object", - "properties": { - "search_method": { - "type": "string", - "description": "用于检索的搜索方法。", - "enum": [ - "hybrid_search", - "semantic_search", - "full_text_search", - "keyword_search" - ] - }, - "reranking_enable": { - "type": "boolean", - "description": "是否启用重新排序模型以改善搜索结果。" - }, - "reranking_mode": { - "type": "string", - "description": "重新排序模式。", - "default": "reranking_model", - "enum": [ - "reranking_model", - "weighted_score" - ] - }, - "reranking_model": { - "type": "object", - "description": "重新排序模型的配置。", - "properties": { - "reranking_provider_name": { - "type": "string", - "description": "重新排序模型的提供商。" - }, - "reranking_model_name": { - "type": "string", - "description": "重新排序模型的名称。" - } - }, - "nullable": true - }, - "top_k": { - "type": "integer", - "description": "返回的顶部匹配结果数量。" - }, - "score_threshold_enabled": { - "type": "boolean", - "description": "是否应用分数阈值来过滤结果。" - }, - "score_threshold": { - "type": "number", - "format": "float", - "description": "结果包含的最低分数。", - "nullable": true - }, - "weights": { - "type": "number", - "format": "float", - "description": "混合搜索模式中语义搜索的权重。", - "nullable": true - } - } - }, - "SummaryIndexSetting": { - "type": "object", - "description": "摘要自动生成配置。", - "properties": { - "enable": { - "type": "boolean", - "description": "是否启用摘要自动生成。" - }, - "model_name": { - "type": "string", - "description": "用于生成摘要的模型名称。" - }, - "model_provider_name": { - "type": "string", - "description": "摘要模型的提供商。" - }, - "summary_prompt": { - "type": "string", - "description": "用于生成摘要的提示词模板。" - } - }, - "required": [ - "enable" - ] - }, - "PreprocessingRule": { - "type": "object", - "description": "文档内容预处理规则。", "properties": { "id": { "type": "string", - "description": "预处理规则的唯一标识符。", - "enum": [ - "remove_extra_spaces", - "remove_urls_emails" - ] + "description": "知识库的唯一标识符。" }, - "enabled": { + "name": { + "type": "string", + "description": "知识库的显示名称。在工作区内唯一。" + }, + "description": { + "type": "string", + "description": "描述知识库用途或内容的可选文本。" + }, + "provider": { + "type": "string", + "description": "提供商类型。内部管理为 `vendor`，外部知识库连接为 `external`。" + }, + "permission": { + "type": "string", + "description": "控制谁可以访问此知识库。可选值：`only_me`、`all_team_members`、`partial_members`。" + }, + "data_source_type": { + "type": "string", + "description": "文档的数据源类型，尚未配置时为 `null`。" + }, + "indexing_technique": { + "type": "string", + "description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。" + }, + "app_count": { + "type": "integer", + "description": "当前使用该知识库的应用数量。" + }, + "document_count": { + "type": "integer", + "description": "知识库中的文档总数。" + }, + "word_count": { + "type": "integer", + "description": "所有文档的总字数。" + }, + "created_by": { + "type": "string", + "description": "创建该知识库的用户 ID。" + }, + "author_name": { + "type": "string", + "description": "创建者的显示名称。" + }, + "created_at": { + "type": "number", + "description": "创建时间戳（Unix 纪元，单位为秒）。" + }, + "updated_by": { + "type": "string", + "description": "最后更新该知识库的用户 ID。" + }, + "updated_at": { + "type": "number", + "description": "最后更新时间戳（Unix 纪元，单位为秒）。" + }, + "embedding_model": { + "type": "string", + "description": "用于索引的嵌入模型名称。" + }, + "embedding_model_provider": { + "type": "string", + "description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。" + }, + "embedding_available": { "type": "boolean", - "description": "此规则是否启用。" - } - } - }, - "SegmentationRule": { - "type": "object", - "description": "将文档内容分割成块的规则。", - "properties": { - "separator": { - "type": "string", - "description": "用于分离段落的自定义分隔符。" + "description": "配置的嵌入模型当前是否可用。" }, - "max_tokens": { - "type": "integer", - "description": "单个段落中允许的最大令牌数。" - } - } - }, - "SubChunkSegmentationRule": { - "type": "object", - "description": "将父块分割为较小子块的规则（用于分层模式）。", - "properties": { - "separator": { - "type": "string", - "description": "子块的分隔符。" - }, - "max_tokens": { - "type": "integer", - "description": "子块的最大令牌长度。" - }, - "chunk_overlap": { - "type": "integer", - "description": "相邻子块之间的重叠令牌数。" - } - } - }, - "ProcessRule": { - "type": "object", - "description": "用于处理文档的规则集，包括清理和分割。", - "properties": { - "mode": { - "type": "string", - "description": "处理模式：automatic、custom 或 hierarchical。", - "enum": [ - "automatic", - "custom", - "hierarchical" - ] - }, - "rules": { + "retrieval_model_dict": { "type": "object", - "description": "要应用的特定规则，当模式为 'custom' 或 'hierarchical' 时使用。", + "description": "知识库的检索配置。", "properties": { - "pre_processing_rules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PreprocessingRule" + "search_method": { + "type": "string", + "description": "用于检索的搜索方式。`keyword_search` 表示关键词匹配，`semantic_search` 表示基于嵌入的语义相似度，`full_text_search` 表示全文索引，`hybrid_search` 表示语义和关键词混合搜索。" + }, + "reranking_enable": { + "type": "boolean", + "description": "是否启用重排序。" + }, + "reranking_mode": { + "type": "string", + "nullable": true, + "description": "重排序模式。`reranking_model` 表示基于模型的重排序，`weighted_score` 表示基于分数的加权。重排序禁用时为 `null`。" + }, + "reranking_model": { + "type": "object", + "description": "重排序模型配置。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "重排序模型的提供商名称。" + }, + "reranking_model_name": { + "type": "string", + "description": "重排序模型名称。" + } } }, - "segmentation": { - "$ref": "#/components/schemas/SegmentationRule" + "weights": { + "type": "object", + "nullable": true, + "description": "混合搜索的权重配置。", + "properties": { + "weight_type": { + "type": "string", + "description": "平衡语义搜索和关键词搜索权重的策略。" + }, + "vector_setting": { + "type": "object", + "description": "语义搜索权重设置。", + "properties": { + "vector_weight": { + "type": "number", + "description": "分配给语义（向量）搜索结果的权重。" + }, + "embedding_provider_name": { + "type": "string", + "description": "用于向量搜索的嵌入模型提供商。" + }, + "embedding_model_name": { + "type": "string", + "description": "用于向量搜索的嵌入模型名称。" + } + } + }, + "keyword_setting": { + "type": "object", + "description": "关键词搜索权重设置。", + "properties": { + "keyword_weight": { + "type": "number", + "description": "分配给关键词搜索结果的权重。" + } + } + } + } }, - "parent_mode": { - "type": "string", - "description": "分层模式中父块的检索模式。", - "enum": [ - "full-doc", - "paragraph" - ] + "top_k": { + "type": "integer", + "description": "返回的最大结果数。" }, - "subchunk_segmentation": { - "$ref": "#/components/schemas/SubChunkSegmentationRule" + "score_threshold_enabled": { + "type": "boolean", + "description": "是否启用分数阈值过滤。" + }, + "score_threshold": { + "type": "number", + "description": "结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。" } - }, - "nullable": true - } - } - }, - "CreateDocumentByTextRequest": { - "type": "object", - "required": [ - "name", - "text" - ], - "properties": { - "name": { - "type": "string", - "description": "文档名称。" + } }, - "text": { - "type": "string", - "description": "文档的完整文本内容。" + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "摘要索引配置。", + "properties": { + "enable": { + "type": "boolean", + "description": "是否已启用摘要索引。" + }, + "model_name": { + "type": "string", + "description": "用于生成摘要的模型名称。" + }, + "model_provider_name": { + "type": "string", + "description": "摘要生成模型的提供商。" + }, + "summary_prompt": { + "type": "string", + "description": "用于摘要生成的提示词模板。" + } + } }, - "indexing_technique": { - "type": "string", - "description": "文档的索引技术。", - "enum": [ - "high_quality", - "economy" - ] + "tags": { + "type": "array", + "description": "与该知识库关联的标签。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "标签标识符。" + }, + "name": { + "type": "string", + "description": "Tag name." + }, + "type": { + "type": "string", + "description": "标签类型。知识库标签始终为 `knowledge`。" + } + } + } }, "doc_form": { "type": "string", - "description": "索引内容的格式。", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] + "description": "文档分块模式。`text_model` 表示标准文本分块，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对提取。" }, - "doc_language": { + "external_knowledge_info": { + "type": "object", + "nullable": true, + "description": "外部知识库的连接详情。当 `provider` 为 `external` 时存在。", + "properties": { + "external_knowledge_id": { + "type": "string", + "description": "外部知识库的 ID。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "外部知识库 API 连接的 ID。" + }, + "external_knowledge_api_name": { + "type": "string", + "description": "外部知识库 API 的显示名称。" + }, + "external_knowledge_api_endpoint": { + "type": "string", + "description": "外部知识库 API 的端点 URL。" + } + } + }, + "external_retrieval_model": { + "type": "object", + "nullable": true, + "description": "外部知识库的检索设置。内部知识库时为 `null`。", + "properties": { + "top_k": { + "type": "integer", + "description": "从外部知识库返回的最大结果数量。" + }, + "score_threshold": { + "type": "number", + "description": "最低相关性得分阈值。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "是否启用分数阈值过滤。" + } + } + }, + "doc_metadata": { + "type": "array", + "description": "知识库的元数据字段定义。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识符。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段值类型。" + } + } + } + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "是否启用内置元数据字段（例如 `document_name`、`uploader`）。" + }, + "pipeline_id": { "type": "string", - "description": "文档的语言，在 Q&A 模式中很重要。", - "example": "中文" + "nullable": true, + "description": "自定义处理流水线的 ID（如果已配置）。" }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { + "runtime_mode": { "type": "string", - "description": "要使用的嵌入模型名称。" + "nullable": true, + "description": "运行时处理模式。" }, - "embedding_model_provider": { + "chunk_structure": { "type": "string", - "description": "嵌入模型的提供商。" + "nullable": true, + "description": "分段结构配置。" }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "摘要自动生成配置。" - } - } - }, - "CreateDocumentByFileRequestData": { - "type": "object", - "description": "从文件创建文档的元数据和规则。", - "properties": { - "original_document_id": { - "type": "string", - "description": "要重新上传或修改的现有文档 ID。", - "format": "uuid" + "icon_info": { + "type": "object", + "nullable": true, + "description": "知识库的图标显示配置。", + "properties": { + "icon_type": { + "type": "string", + "description": "图标类型。" + }, + "icon": { + "type": "string", + "description": "图标标识符或表情符号。" + }, + "icon_background": { + "type": "string", + "description": "图标的背景颜色。" + }, + "icon_url": { + "type": "string", + "description": "自定义图标图片的 URL。" + } + } }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] + "is_published": { + "type": "boolean", + "description": "知识库是否已发布。" }, - "doc_form": { - "type": "string", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] + "total_documents": { + "type": "integer", + "description": "文档总数。" }, - "doc_language": { - "type": "string", - "example": "中文" + "total_available_documents": { + "type": "integer", + "description": "已启用且可用的文档数量。" }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + "enable_api": { + "type": "boolean", + "description": "该知识库是否启用 API 访问。" }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { - "type": "string" - }, - "embedding_model_provider": { - "type": "string" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "摘要自动生成配置。" - } - } - }, - "UpdateDocumentByTextRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "文档的新名称（可选）。" - }, - "text": { - "type": "string", - "description": "文档的新文本内容（可选）。" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - } - } - }, - "UpdateDocumentByFileRequestData": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "文档的新名称（可选）。" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + "is_multimodal": { + "type": "boolean", + "description": "是否启用多模态内容处理。" } } }, @@ -2086,1023 +6225,431 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "description": "文档的唯一标识符。" }, "position": { - "type": "integer" + "type": "integer", + "description": "文档在列表中的显示位置。" }, "data_source_type": { - "type": "string" + "type": "string", + "description": "文档的创建方式。文件上传为 `upload_file`，Notion 导入为 `notion_import`。" }, "data_source_info": { "type": "object", - "nullable": true + "description": "原始数据源信息，随 `data_source_type` 而异。" + }, + "data_source_detail_dict": { + "type": "object", + "description": "详细的数据源信息，包括文件详情。" }, "dataset_process_rule_id": { "type": "string", - "format": "uuid", - "nullable": true + "description": "应用于该文档的处理规则 ID。" }, "name": { - "type": "string" + "type": "string", + "description": "文档名称。" }, "created_from": { - "type": "string" + "type": "string", + "description": "文档来源。通过 API 创建时为 `api`，通过 UI 创建时为 `web`。" }, "created_by": { "type": "string", - "format": "uuid" + "description": "创建该文档的用户 ID。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "创建时间戳（Unix 纪元，单位为秒）。" }, "tokens": { - "type": "integer" + "type": "integer", + "description": "文档中的令牌总数。" }, "indexing_status": { - "type": "string" + "type": "string", + "description": "当前索引状态。`waiting` 表示排队中，`parsing` 表示正在提取内容，`cleaning` 表示正在去噪，`splitting` 表示正在分块，`indexing` 表示正在构建向量，`completed` 表示就绪，`error` 表示失败，`paused` 表示手动暂停。" }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "索引失败时的错误消息。无错误时为 `null`。" }, "enabled": { - "type": "boolean" + "type": "boolean", + "description": "该文档是否启用检索。" }, "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true + "type": "number", + "nullable": true, + "description": "文档被禁用的时间戳。启用时为 `null`。" }, "disabled_by": { "type": "string", - "format": "uuid", - "nullable": true + "nullable": true, + "description": "禁用该文档的用户 ID。启用时为 `null`。" }, "archived": { - "type": "boolean" + "type": "boolean", + "description": "文档是否已归档。" }, "display_status": { - "type": "string" + "type": "string", + "description": "基于 `indexing_status` 和 `enabled` 状态派生的面向用户的显示状态。" }, "word_count": { - "type": "integer" + "type": "integer", + "description": "文档的总字数。" }, "hit_count": { - "type": "integer" + "type": "integer", + "description": "该文档在检索查询中被匹配的次数。" }, "doc_form": { - "type": "string" - } - } - }, - "DocumentCreationResponse": { - "type": "object", - "properties": { - "document": { - "$ref": "#/components/schemas/Document" - }, - "batch": { "type": "string", - "description": "用于跟踪索引进度的批次标识符。" - } - } - }, - "CreateDatasetRequest": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "知识库的名称。" + "description": "文档分块模式。`text_model` 表示标准文本分块，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对提取。" }, - "description": { - "type": "string", - "description": "知识库的描述（可选）。" - }, - "indexing_technique": { - "type": "string", - "description": "要使用的索引技术。", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "description": "知识库的访问权限。", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "provider": { - "type": "string", - "description": "知识库的提供商。", - "enum": [ - "vendor", - "external" - ] - }, - "external_knowledge_api_id": { - "type": "string", - "description": "外部知识 API 的 ID（如果提供商是 'external'）。" - }, - "external_knowledge_id": { - "type": "string", - "description": "外部知识的 ID（如果提供商是 'external'）。" - }, - "embedding_model": { - "type": "string", - "description": "嵌入模型的名称。" - }, - "embedding_model_provider": { - "type": "string", - "description": "嵌入模型的提供商。" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "摘要自动生成配置。" - } - } - }, - "Dataset": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string", - "nullable": true - }, - "provider": { - "type": "string" - }, - "permission": { - "type": "string" - }, - "data_source_type": { - "type": "string", - "nullable": true - }, - "indexing_technique": { - "type": "string", - "nullable": true - }, - "app_count": { - "type": "integer" - }, - "document_count": { - "type": "integer" - }, - "word_count": { - "type": "integer" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - }, - "updated_by": { - "type": "string", - "format": "uuid" - }, - "updated_at": { - "type": "integer", - "format": "int64" - }, - "embedding_model": { - "type": "string", - "nullable": true - }, - "embedding_model_provider": { - "type": "string", - "nullable": true - }, - "embedding_available": { - "type": "boolean", - "nullable": true - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "该数据集的摘要自动生成配置。", - "nullable": true - } - } - }, - "DatasetListResponse": { - "type": "object", - "properties": { - "data": { + "doc_metadata": { "type": "array", - "items": { - "$ref": "#/components/schemas/Dataset" - } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - }, - "DatasetDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Dataset" - }, - { - "type": "object", - "properties": { - "retrieval_model_dict": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "tags": { - "type": "array", - "items": { - "type": "object" - } - }, - "doc_form": { - "type": "string", - "nullable": true - } - } - } - ] - }, - "UpdateDatasetRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "知识库的新名称。" - }, - "description": { - "type": "string", - "description": "知识库的新描述。" - }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "embedding_model_provider": { - "type": "string" - }, - "embedding_model": { - "type": "string" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "partial_member_list": { - "type": "array", - "description": "'partial_members' 权限可访问的成员列表。", + "description": "分配给该文档的元数据值。", "items": { "type": "object", - "required": [ - "user_id" - ], "properties": { - "user_id": { + "id": { "type": "string", - "description": "成员的用户 ID。" + "description": "元数据字段标识符。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段值类型。" + }, + "value": { + "type": "string", + "description": "此文档的元数据值。" } } } }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "摘要自动生成配置。" - } - } - }, - "IndexingStatus": { - "type": "object", - "properties": { - "id": { + "summary_index_status": { "type": "string", - "format": "uuid" + "nullable": true, + "description": "该文档的摘要索引状态。未配置摘要索引时为 `null`。" }, - "indexing_status": { - "type": "string" - }, - "processing_started_at": { - "type": "number", - "format": "float" - }, - "parsing_completed_at": { - "type": "number", - "format": "float" - }, - "cleaning_completed_at": { - "type": "number", - "format": "float" - }, - "splitting_completed_at": { - "type": "number", - "format": "float" - }, - "completed_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "paused_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "error": { - "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "completed_segments": { - "type": "integer" - }, - "total_segments": { - "type": "integer" + "need_summary": { + "type": "boolean", + "description": "是否需要为该文档生成摘要。" } } }, - "DocumentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" - } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - }, - "DocumentDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Document" - }, - { - "type": "object", - "properties": { - "dataset_process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "document_process_rule": { - "allOf": [ - { - "$ref": "#/components/schemas/ProcessRule" - }, - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "dataset_id": { - "type": "string" - } - } - } - ] - }, - "indexing_latency": { - "type": "number", - "format": "float", - "nullable": true - }, - "segment_count": { - "type": "integer" - }, - "average_segment_length": { - "type": "integer" - }, - "doc_language": { - "type": "string", - "nullable": true - } - } - } - ] - }, "Segment": { "type": "object", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "分段的唯一标识符。" }, "position": { - "type": "integer" + "type": "integer", + "description": "分段在文档中的位置。" }, "document_id": { "type": "string", - "format": "uuid" + "description": "该分段所属文档的 ID。" }, "content": { - "type": "string" + "type": "string", + "description": "分段的文本内容。" + }, + "sign_content": { + "type": "string", + "description": "用于完整性验证的签名内容哈希。" }, "answer": { "type": "string", - "nullable": true + "description": "回答内容，用于问答模式文档。" }, "word_count": { - "type": "integer" + "type": "integer", + "description": "分段内容的字数。" }, "tokens": { - "type": "integer" + "type": "integer", + "description": "分段内容的令牌数。" }, "keywords": { "type": "array", + "description": "与该分段关联的关键词，用于基于关键词的检索。", "items": { "type": "string" } }, "index_node_id": { - "type": "string" + "type": "string", + "description": "向量存储中索引节点的 ID。" }, "index_node_hash": { - "type": "string" + "type": "string", + "description": "索引内容的哈希值，用于检测变更。" }, "hit_count": { - "type": "integer" + "type": "integer", + "description": "该分段在检索查询中被匹配的次数。" }, "enabled": { - "type": "boolean" + "type": "boolean", + "description": "该分段是否启用检索。" }, "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true + "type": "number", + "nullable": true, + "description": "分段被禁用的时间戳。启用时为 `null`。" }, "disabled_by": { "type": "string", - "format": "uuid", - "nullable": true + "nullable": true, + "description": "禁用该分段的用户 ID。启用时为 `null`。" }, "status": { - "type": "string" + "type": "string", + "description": "分段的当前索引状态，例如 `completed`、`indexing`、`error`。" }, "created_by": { "type": "string", - "format": "uuid" + "description": "创建该分段的用户 ID。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "创建时间戳（Unix 纪元，单位为秒）。" + }, + "updated_at": { + "type": "number", + "description": "最后更新时间戳（Unix 纪元，单位为秒）。" + }, + "updated_by": { + "type": "string", + "description": "最后更新该分段的用户 ID。" }, "indexing_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "索引开始的时间戳。尚未开始时为 `null`。" }, "completed_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "索引完成的时间戳。尚未完成时为 `null`。" }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "索引失败时的错误消息。无错误时为 `null`。" }, "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true + "type": "number", + "nullable": true, + "description": "索引停止的时间戳。未停止时为 `null`。" + }, + "child_chunks": { + "type": "array", + "description": "属于该分段的子分段。仅在分层模式文档中存在。", + "items": { + "$ref": "#/components/schemas/ChildChunk" + } + }, + "attachments": { + "type": "array", + "description": "附加到该分段的文件。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "附件文件标识符。" + }, + "name": { + "type": "string", + "description": "原始文件名。" + }, + "size": { + "type": "integer", + "description": "文件大小（字节）。" + }, + "extension": { + "type": "string", + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "description": "文件的 MIME 类型。" + }, + "source_url": { + "type": "string", + "description": "访问附件的 URL。" + } + } + } }, "summary": { "type": "string", - "nullable": true - } - } - }, - "CreateSegmentsRequest": { - "type": "object", - "properties": { - "segments": { - "type": "array", - "items": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "块的文本内容（Q&A 模式中为问题）。" - }, - "answer": { - "type": "string", - "description": "答案内容，如果文档处于 Q&A 模式则必需。" - }, - "keywords": { - "type": "array", - "description": "与块关联的关键词。", - "items": { - "type": "string" - } - } - } - } - } - } - }, - "SegmentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Segment" - } - }, - "doc_form": { - "type": "string" - } - } - }, - "SegmentPaginatedResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/SegmentListResponse" - }, - { - "type": "object", - "properties": { - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - } - ] - }, - "SegmentDetailResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Segment" - }, - "doc_form": { - "type": "string" - } - } - }, - "UpdateSegmentRequest": { - "type": "object", - "properties": { - "segment": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string" - }, - "answer": { - "type": "string" - }, - "keywords": { - "type": "array", - "items": { - "type": "string" - } - }, - "enabled": { - "type": "boolean" - }, - "regenerate_child_chunks": { - "type": "boolean", - "description": "是否重新生成子块（分层模式）。" - } - } - } - } - }, - "RetrieveRequest": { - "type": "object", - "required": [ - "query" - ], - "properties": { - "query": { - "type": "string", - "description": "搜索查询字符串。" - }, - "retrieval_model": { - "allOf": [ - { - "$ref": "#/components/schemas/RetrievalModel" - }, - { - "type": "object", - "properties": { - "metadata_filtering_conditions": { - "type": "object", - "description": "基于元数据过滤结果的条件。", - "properties": { - "logical_operator": { - "type": "string", - "enum": [ - "and", - "or" - ] - }, - "conditions": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "元数据字段的名称。" - }, - "comparison_operator": { - "type": "string", - "description": "比较的运算符。" - }, - "value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } - ], - "nullable": true, - "description": "要比较的值。" - } - } - } - } - } - } - } - } - ] - } - } - }, - "RetrievedSegment": { - "type": "object", - "properties": { - "segment": { - "allOf": [ - { - "$ref": "#/components/schemas/Segment" - }, - { - "type": "object", - "properties": { - "document": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "data_source_type": { - "type": "string" - }, - "name": { - "type": "string" - } - } - } - } - } - ] - }, - "score": { - "type": "number", - "format": "float" - } - } - }, - "RetrieveResponse": { - "type": "object", - "properties": { - "query": { - "type": "object", - "properties": { - "content": { - "type": "string" - } - } - }, - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RetrievedSegment" - } - } - } - }, - "Model": { - "type": "object", - "properties": { - "model": { - "type": "string" - }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "model_type": { - "type": "string" - }, - "features": { - "type": "array", - "items": {}, - "nullable": true - }, - "fetch_from": { - "type": "string" - }, - "model_properties": { - "type": "object", - "properties": { - "context_size": { - "type": "integer" - } - } - }, - "deprecated": { - "type": "boolean" - }, - "status": { - "type": "string" - }, - "load_balancing_enabled": { - "type": "boolean" - } - } - }, - "ModelProvider": { - "type": "object", - "properties": { - "provider": { - "type": "string" - }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "icon_small": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } - }, - "icon_large": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } - }, - "status": { - "type": "string" - }, - "models": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Model" - } + "nullable": true, + "description": "AI 生成的分段内容摘要。未启用摘要索引时为 `null`。" } } }, "ChildChunk": { "type": "object", - "description": "表示分层分割中的子块。", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "子分段的唯一标识符。" }, "segment_id": { "type": "string", - "format": "uuid" + "description": "该子分段所属的父分段 ID。" }, "content": { - "type": "string" + "type": "string", + "description": "子分段的文本内容。" + }, + "position": { + "type": "integer", + "description": "子分段在父分段中的位置。" }, "word_count": { - "type": "integer" - }, - "tokens": { - "type": "integer" - }, - "index_node_id": { - "type": "string" - }, - "index_node_hash": { - "type": "string" - }, - "status": { - "type": "string" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { "type": "integer", - "format": "int64" - }, - "indexing_at": { - "type": "integer", - "format": "int64" - }, - "completed_at": { - "type": "integer", - "format": "int64" - }, - "error": { - "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true - } - } - }, - "CreateChildChunkRequest": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "子块的内容。" - } - } - }, - "UpdateChildChunkRequest": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "子块的更新内容。" - } - } - }, - "ChildChunkResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ChildChunk" - } - } - }, - "ChildChunkListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ChildChunk" - } - }, - "total": { - "type": "integer" - }, - "total_pages": { - "type": "integer" - }, - "page": { - "type": "integer" - }, - "limit": { - "type": "integer" - } - } - }, - "UploadFileResponse": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "size": { - "type": "integer" - }, - "extension": { - "type": "string" - }, - "url": { - "type": "string", - "format": "uri", - "description": "文件的预览 URL。" - }, - "download_url": { - "type": "string", - "format": "uri", - "description": "文件的下载 URL。" - }, - "mime_type": { - "type": "string" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - } - } - }, - "Tag": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" + "description": "子分段内容的字数。" }, "type": { "type": "string", - "example": "knowledge" + "description": "子分段的创建方式。系统生成为 `automatic`，手动创建为 `custom`。" }, - "binding_count": { - "type": "integer" + "created_at": { + "type": "number", + "description": "创建时间戳（Unix 纪元，单位为秒）。" + }, + "updated_at": { + "type": "number", + "description": "最后更新时间戳（Unix 纪元，单位为秒）。" } } + }, + "RetrievalModel": { + "type": "object", + "required": [ + "search_method", + "reranking_enable", + "top_k", + "score_threshold_enabled" + ], + "properties": { + "search_method": { + "type": "string", + "description": "用于检索的搜索方法。", + "enum": [ + "keyword_search", + "semantic_search", + "full_text_search", + "hybrid_search" + ] + }, + "reranking_enable": { + "type": "boolean", + "description": "是否启用重排序。" + }, + "reranking_model": { + "type": "object", + "description": "重排序模型配置。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "重排序模型的提供商名称。" + }, + "reranking_model_name": { + "type": "string", + "description": "重排序模型名称。" + } + } + }, + "reranking_mode": { + "type": "string", + "enum": [ + "reranking_model", + "weighted_score" + ], + "nullable": true, + "description": "重排序模式。当 `reranking_enable` 为 `true` 时必填。" + }, + "top_k": { + "type": "integer", + "description": "返回的最大结果数。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "是否启用分数阈值过滤。" + }, + "score_threshold": { + "type": "number", + "nullable": true, + "description": "结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。" + }, + "weights": { + "type": "object", + "nullable": true, + "description": "混合搜索的权重配置。", + "properties": { + "weight_type": { + "type": "string", + "description": "平衡语义搜索和关键词搜索权重的策略。", + "enum": [ + "semantic_first", + "keyword_first", + "customized" + ] + }, + "vector_setting": { + "type": "object", + "description": "语义搜索权重设置。", + "properties": { + "vector_weight": { + "type": "number", + "description": "分配给语义（向量）搜索结果的权重。" + }, + "embedding_provider_name": { + "type": "string", + "description": "用于向量搜索的嵌入模型提供商。" + }, + "embedding_model_name": { + "type": "string", + "description": "用于向量搜索的嵌入模型名称。" + } + } + }, + "keyword_setting": { + "type": "object", + "description": "关键词搜索权重设置。", + "properties": { + "keyword_weight": { + "type": "number", + "description": "分配给关键词搜索结果的权重。" + } + } + } + } + } + } + } + }, + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**" } } } diff --git a/zh/api-reference/openapi_workflow.json b/zh/api-reference/openapi_workflow.json index ed9742e9..17f6ca3c 100644 --- a/zh/api-reference/openapi_workflow.json +++ b/zh/api-reference/openapi_workflow.json @@ -1,18 +1,18 @@ { "openapi": "3.0.1", "info": { - "title": "Workflow 应用 API", - "description": "Workflow 应用无会话支持，适合用于翻译/文章写作/总结 AI 等等。", + "title": "工作流应用 API", + "description": "工作流应用提供无会话支持，适用于翻译、文章写作、摘要 AI 等场景。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API 的基础 URL。请将 {api_base_url} 替换为你的应用提供的实际 API 基础 URL。", + "description": "工作流应用 API 的基础 URL。将 {api_base_url} 替换为实际的 API 基础 URL。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "实际的 API 基础 URL" + "description": "API 的实际基础 URL" } } } @@ -25,37 +25,49 @@ "paths": { "/workflows/run": { "post": { - "summary": "执行 workflow", - "description": "执行 workflow，没有已发布的 workflow，不可执行。", + "summary": "执行工作流", + "description": "执行工作流。没有已发布的工作流时无法执行。", "operationId": "executeWorkflowCn", - "tags": ["工作流执行"], + "tags": [ + "工作流" + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowExecutionRequestCn" + "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { - "basic_execution_cn": { - "summary": "基础工作流执行示例", + "streaming_example": { + "summary": "请求示例 - 流式模式", "value": { "inputs": { - "query": "请总结这段文字：..." + "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", - "user": "workflow_user_001" + "user": "user_workflow_123" } }, - "with_file_array_variable_cn":{ - "summary": "包含文件列表变量的输入示例", + "blocking_example": { + "summary": "请求示例 - 阻塞模式", + "value": { + "inputs": { + "query": "Translate this to French: Hello world" + }, + "response_mode": "blocking", + "user": "user_workflow_456" + } + }, + "with_file_array_variable": { + "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", - "upload_file_id": "已上传的文件ID_abc" + "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", @@ -65,7 +77,7 @@ ] }, "response_mode": "blocking", - "user": "workflow_user_002" + "user": "user_workflow_789" } } } @@ -74,67 +86,606 @@ }, "responses": { "200": { - "description": "工作流执行成功。响应结构取决于 `response_mode`。\n- `blocking`: `application/json` 格式，包含 `WorkflowCompletionResponseCn` 对象。\n- `streaming`: `text/event-stream` 格式，包含 `ChunkWorkflowEventCn` 事件流。", + "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `WorkflowBlockingResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkWorkflowEvent` 对象流。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowCompletionResponseCn" + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "响应示例 - 阻塞模式", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Bonjour le monde" + }, + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630 + } + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "SSE 事件流。每个事件以 'data: ' 开头，以 '\\n\\n' 结尾。具体结构请参见 `ChunkWorkflowEventCn`。" + "description": "服务器发送事件 (SSE) 流。每个事件是一个以 `data: ` 为前缀的 JSON 对象，以两个换行符终止。\n\n**SSE 解析指南：**每个事件是一行以 `data: ` 为前缀的 JSON 对象，以 `\\n\\n` 终止。解析 JSON 前先去除 `data: ` 前缀。JSON 内的 `event` 字段决定事件类型。当收到终止事件（如 `message_end`、`workflow_finished` 或 `error`）时流结束。忽略 `ping` 事件（每 10 秒发送一次以保持连接活跃）。注意即使流中出现错误事件，HTTP 状态码仍为 `200`。" + }, + "examples": { + "streamingResponse": { + "summary": "响应示例 - 流式模式", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestWorkflowCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 工作流 execution request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 上游模型提供商的速率限制已超出。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal Server Error." + } + } + } + } + } + } + } + } + }, + "/workflows/{workflow_id}/run": { + "post": { + "summary": "按 ID 执行工作流", + "description": "通过 ID 执行指定的工作流版本。适用于运行工作流的特定已发布版本。", + "operationId": "runWorkflowByIdZh", + "tags": [ + "工作流" + ], + "parameters": [ + { + "name": "workflow_id", + "in": "path", + "required": true, + "description": "要执行的特定版本的工作流 ID。此值在 [执行工作流](/api-reference/工作流/执行-工作流) 响应和 [获取工作流运行详情](/api-reference/工作流/获取-工作流-执行情况) 的 `workflow_id` 字段中返回。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowExecutionRequest" + }, + "examples": { + "example": { + "summary": "请求示例", + "value": { + "inputs": { + "query": "Summarize this article" + }, + "response_mode": "blocking", + "user": "user_workflow_123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `WorkflowBlockingResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkWorkflowEvent` 对象流。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "响应示例 - 阻塞模式", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Article summary here" + }, + "error": null, + "elapsed_time": 2.45, + "total_tokens": 280, + "total_steps": 4, + "created_at": 1705407629, + "finished_at": 1705407631 + } + } + } + } + }, + "text/event-stream": { + "schema": { + "type": "string", + "description": "服务器发送事件 (SSE) 流。每个事件是一个以 `data: ` 为前缀的 JSON 对象，以两个换行符终止。\n\n**SSE 解析指南：**每个事件是一行以 `data: ` 为前缀的 JSON 对象，以 `\\n\\n` 终止。解析 JSON 前先去除 `data: ` 前缀。JSON 内的 `event` 字段决定事件类型。当收到终止事件（如 `message_end`、`workflow_finished` 或 `error`）时流结束。忽略 `ping` 事件（每 10 秒发送一次以保持连接活跃）。注意即使流中出现错误事件，HTTP 状态码仍为 `200`。" + } + } + } + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : 工作流 is a draft or has an invalid ID format.\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 工作流 execution request failed.\n- `invalid_param` : Required parameter missing or invalid.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Workflow is a draft and cannot be executed." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 工作流 not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 上游模型提供商的速率限制已超出。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + }, + "rate_limit_error": { + "summary": "rate_limit_error", + "value": { + "status": 429, + "code": "rate_limit_error", + "message": "Rate Limit Error" + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal Server Error." + } + } + } + } + } + } } } }, "/workflows/run/{workflow_run_id}": { "get": { - "summary": "获取workflow执行情况", - "description": "根据 workflow 执行 ID 获取 workflow 任务当前执行结果。", + "summary": "获取工作流执行情况", + "description": "根据工作流执行 ID 获取工作流任务的当前执行结果。", "operationId": "getWorkflowRunDetailCn", - "tags": ["工作流执行"], + "tags": [ + "工作流" + ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, - "description": "workflow 执行 ID，可在流式返回 Chunk 或阻塞模式响应中获取。", - "schema": { "type": "string", "format": "uuid" } + "description": "工作流运行 ID，可从工作流执行响应或流式事件中获取。", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "成功获取 workflow 执行详情。", + "description": "成功获取工作流运行详情。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponseCn" } + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "响应示例", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } } } }, - "404": {"description": "Workflow 执行记录未找到。"} + "400": { + "description": "`not_workflow_app` : 应用模式与 API 路由不匹配。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未找到工作流运行记录。", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } + } + } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "获取工作流日志", + "description": "获取分页的工作流执行日志，支持筛选选项。", + "operationId": "getWorkflowLogsCn", + "tags": [ + "工作流" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "在日志中搜索的关键词。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "按执行状态筛选。", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "分页页码。", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页条目数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "筛选在此 ISO 8601 时间戳之前创建的日志。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "筛选在此 ISO 8601 时间戳之后创建的日志。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "按终端用户会话 ID 筛选。", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "按账户 ID 筛选。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "成功获取工作流日志。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "响应示例", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0, + "triggered_from": "app" + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_workflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } } } }, "/workflows/tasks/{task_id}/stop": { "post": { - "summary": "停止响应 (Workflow Task)", - "description": "停止 workflow 任务的生成。仅支持流式模式。", + "summary": "停止工作流任务", + "description": "停止正在运行的工作流任务。仅在 `streaming` 模式下支持。", "operationId": "stopWorkflowTaskGenerationCn", - "tags": ["工作流执行"], + "tags": [ + "工作流" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "任务 ID，可在流式返回 Chunk 中获取。", - "schema": { "type": "string", "format": "uuid" } + "description": "任务 ID，可以从 [执行工作流](/api-reference/工作流/执行-工作流) API 的流式分块返回中获取。", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -143,305 +694,3156 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { - "user": { "type": "string", "description": "用户标识，必须和执行 workflow 接口传入的 user 保持一致。" } + "user": { + "type": "string", + "description": "用户标识符，必须与 [执行工作流](/api-reference/工作流/执行-工作流) 请求中传递的用户一致。" + } + } + }, + "examples": { + "example": { + "summary": "请求示例", + "value": { + "user": "user_workflow_123" + } } } } } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "- `not_workflow_app` : 应用模式与 API 路由不匹配。\n- `invalid_param` : 必要参数缺失或无效。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + } } } }, "/files/upload": { "post": { - "summary": "上传文件 (Workflow)", - "description": "上传文件并在执行 workflow 时使用。支持你的工作流程所支持的任何格式。上传的文件仅供当前终端用户使用。", "operationId": "uploadWorkflowFileCn", - "tags": ["文件操作 (Workflow)"], + "tags": [ + "文件操作" + ], + "summary": "上传文件", + "description": "上传文件用于发送消息时使用，支持图片、文档、音频和视频的多模态理解。上传的文件仅供当前终端用户使用。", "requestBody": { + "description": "文件上传请求。需要 multipart/form-data 格式。", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "file" + ], "properties": { - "file": { "type": "string", "format": "binary", "description": "要上传的文件。" }, - "user": { "type": "string", "description": "用户标识。" } + "file": { + "type": "string", + "format": "binary", + "description": "要上传的文件。支持的类型包括图片、文档、音频和视频。" + }, + "user": { + "type": "string", + "description": "用户标识符，由开发者定义的规则生成，必须在应用内唯一。" + } } } } } }, "responses": { - "200": { "description": "文件上传成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseCn" } } } }, - "201": { "description": "文件创建成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseCn" } } } }, - "400": { "$ref": "#/components/responses/BadRequestFileCn" }, - "413": { "$ref": "#/components/responses/FileTooLargeCn" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileCn" }, - "503": { "$ref": "#/components/responses/S3ErrorFileCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } + "201": { + "description": "文件上传成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "响应示例", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "product-photo.png", + "size": 204800, + "extension": "png", + "mime_type": "image/png", + "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "created_at": 1705407629, + "preview_url": null, + "source_url": null, + "original_url": null, + "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "conversation_id": null, + "file_key": "uploads/product-photo.png" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : 请求中未提供文件。\n- `too_many_files` : 每次请求仅允许上传一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + } + } + } + } + }, + "413": { + "description": "`file_too_large` : 文件大小超出限制。", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : 不允许的文件类型。", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } + } + } + }, + "/files/{file_id}/preview": { + "get": { + "operationId": "downloadWorkflowFileZh", + "tags": [ + "文件操作" + ], + "summary": "下载文件", + "description": "预览或下载之前通过[上传文件](/api-reference/文件操作/上传文件) API 上传的文件。仅可访问属于请求应用内消息的文件。", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "要预览的文件唯一标识符，从 [上传文件](/api-reference/文件操作/上传文件) API 响应中获取。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "如果为 `true`，则强制文件以附件形式下载，而不是在浏览器中预览。", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "用户标识符，用于终端用户上下文。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "返回原始文件内容。`Content-Type` 头设置为文件的 MIME 类型。如果 `as_attachment` 为 `true`，文件将以 `Content-Disposition: attachment` 方式作为下载返回。", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : 拒绝访问请求的文件。", + "content": { + "application/json": { + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } + } + } + }, + "404": { + "description": "`file_not_found` : 未找到请求的文件。", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } } } }, "/end-users/{end_user_id}": { "get": { - "summary": "获取终端用户", - "description": "通过 ID 获取终端用户信息。\n\n当其他 API 返回终端用户 ID（例如文件上传接口返回的 `created_by`）时，可使用该接口查询对应的终端用户信息。", "operationId": "getEndUserWorkflowCn", - "tags": ["终端用户"], + "tags": [ + "终端用户" + ], + "summary": "获取终端用户信息", + "description": "根据 ID 获取终端用户信息。当其他 API 返回终端用户 ID（例如[上传文件](/api-reference/文件操作/上传文件)返回的 `created_by`）时很有用。", "parameters": [ { "name": "end_user_id", "in": "path", "required": true, "description": "终端用户 ID。", - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { "200": { - "description": "成功获取终端用户信息。", + "description": "成功获取终端用户。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailCn" } + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "响应示例", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } + "404": { + "description": "`end_user_not_found` : 未找到终端用户。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } } } }, - "/workflows/logs": { - "get": { - "summary": "获取 workflow 日志", - "description": "倒序返回 workflow 日志。", - "operationId": "getWorkflowLogsCn", - "tags": ["工作流执行"], - "parameters": [ - { "name": "keyword", "in": "query", "description": "（可选）关键字。", "schema": { "type": "string" } }, - { "name": "status", "in": "query", "description": "（可选）执行状态：succeeded, failed, stopped, running。", "schema": { "type": "string", "enum": ["succeeded", "failed", "stopped", "running"] } }, - { "name": "page", "in": "query", "description": "（可选）当前页码, 默认1。", "schema": { "type": "integer", "default": 1 } }, - { "name": "limit", "in": "query", "description": "（可选）每页条数, 默认20。", "schema": { "type": "integer", "default": 20 } } - ], - "responses": { - "200": { "description": "成功获取 workflow 日志。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponseCn" } } } } + "/audio-to-text": { + "post": { + "operationId": "workflowAudioToTextZh", + "tags": [ + "语音与文字转换" + ], + "summary": "语音转文字", + "description": "将音频文件转换为文字。支持的格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件大小限制为 `30 MB`。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } } + } + }, + "responses": { + "200": { + "description": "语音转文字成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "响应示例", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `no_audio_uploaded` : 未上传音频文件。\n- `provider_not_support_speech_to_text` : 模型提供商不支持语音转文字。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 语音识别请求失败。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音频文件大小超出限制。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 不允许的音频类型。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } } + } + }, + "/text-to-audio": { + "post": { + "operationId": "workflowTextToAudioZh", + "tags": [ + "语音与文字转换" + ], + "summary": "文字转语音", + "description": "将文字转换为语音。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "请求示例", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "返回生成的音频文件。`Content-Type` 头设置为音频 MIME 类型（例如 `audio/wav`、`audio/mp3`）。如果 `streaming` 为 `true`，音频将以分块传输编码方式流式返回。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `provider_not_initialize` : 未找到有效的模型提供商凭据。\n- `provider_quota_exceeded` : 模型提供商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 文字转语音请求失败。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内部服务器错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } }, "/info": { "get": { - "summary": "获取应用基本信息 (Workflow)", "operationId": "getWorkflowAppInfoCn", - "tags": ["应用配置 (Workflow)"], - "responses": { "200": { "description": "应用基本信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "summary": "获取应用基本信息", + "description": "获取应用的基本信息，包括名称、描述、标签和模式。", + "responses": { + "200": { + "description": "应用的基本信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "响应示例", + "value": { + "name": "My Workflow App", + "description": "一个有用的客服聊天机器人。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "workflow", + "author_name": "Dify Team" + } + } + } + } + } + } + } } }, "/parameters": { "get": { - "summary": "获取应用参数 (Workflow)", "operationId": "getWorkflowAppParametersCn", - "tags": ["应用配置 (Workflow)"], - "responses": { "200": { "description": "应用参数信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowAppParametersResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "summary": "获取应用参数", + "description": "获取应用的输入表单配置，包括功能开关、输入参数名称、类型和默认值。", + "responses": { + "200": { + "description": "应用参数信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "响应示例", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : 应用不可用或配置错误。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getWorkflowAppMetaZh", + "tags": [ + "应用配置" + ], + "summary": "获取应用元数据", + "description": "获取应用的元数据，包括工具图标和其他配置详情。", + "responses": { + "200": { + "description": "成功获取应用元数据。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "响应示例", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } } }, "/site": { "get": { - "summary": "获取应用 WebApp 设置 (Workflow)", "operationId": "getWorkflowWebAppSettingsCn", - "tags": ["应用配置 (Workflow)"], - "responses": { "200": { "description": "WebApp 设置信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWebAppSettingsResponseCn" } } } } } + "tags": [ + "应用配置" + ], + "summary": "获取应用 WebApp 设置", + "description": "获取应用的 WebApp 设置，包括站点配置、主题和自定义选项。", + "responses": { + "200": { + "description": "应用的 WebApp 设置。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "响应示例", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🤖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "一个有用的客服聊天机器人。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 未找到此应用的站点或工作空间已归档。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key 鉴权。所有 API 请求都应在 Authorization HTTP Header 中包含你的 API-Key，格式为：Bearer {API_KEY}。强烈建议开发者把 API-Key 放在后端存储，而非客户端，以免泄露。" } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**" + } }, "responses": { - "BadRequestWorkflowCn": { "description": "请求参数错误或工作流执行失败。可能错误码：invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, workflow_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "BadRequestFileCn": { "description": "文件操作请求错误。可能错误码：no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "FileTooLargeCn": { "description": "文件太大 (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "UnsupportedFileTypeFileCn": { "description": "不支持的文件类型 (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "S3ErrorFileCn": { "description": "S3 存储服务错误。可能错误码：s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "InternalServerErrorCn": { "description": "服务内部异常。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "SuccessResultCn": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "EndUserNotFoundCn": { "description": "终端用户不存在。错误码：`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } } + "SuccessResult": { + "description": "操作成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "success" + ], + "description": "操作结果。" + } + } + }, + "examples": { + "success": { + "summary": "响应示例", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "WorkflowExecutionRequestCn": { + "WorkflowExecutionRequest": { "type": "object", - "required": ["inputs", "response_mode", "user"], + "required": [ + "inputs", + "user" + ], "properties": { "inputs": { "type": "object", - "description": "允许传入 App 定义的各变量值。如果变量是文件列表类型，该变量对应的值应是 InputFileObjectWorkflowCn 对象的列表。", + "description": "工作流输入变量的键值对。文件类型变量的值应为文件对象数组，包含 `type`、`transfer_method` 以及 `url` 或 `upload_file_id`。请参阅 [获取应用参数](/api-reference/应用配置/获取应用参数) 响应中的 `user_input_form` 字段，以了解应用所需的变量名称和类型。", "additionalProperties": { - "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectWorkflowCn" } } ] - }, - "example": { "user_query": "请帮我翻译这句话。", "target_language": "法语" } + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "object" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + } + } + ] + } }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "description": "返回响应模式。streaming (推荐) 基于 SSE；blocking 等待执行完毕后返回 (Cloudflare 100秒超时限制)。" }, - "user": { "type": "string", "description": "用户标识，应用内唯一。" } + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "响应模式。使用 `blocking` 获取同步响应（Cloudflare 超时时间为 `100 s`），使用 `streaming` 获取服务器发送事件。未指定时默认为阻塞模式。" + }, + "user": { + "type": "string", + "description": "用户标识符，由开发者自定义规则，在应用内必须唯一。此标识符用于限定数据访问范围——工作流运行和文件仅在使用相同的 `user` 值查询时可见。" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + }, + "nullable": true, + "description": "文件列表。适用于需要将文件与文本组合输入的场景，仅在模型支持 Vision 能力时可用。要附加本地文件，请先通过 [上传文件](/api-reference/文件操作/上传文件) 上传，然后将返回的 `id` 作为 `upload_file_id`，并设置 `transfer_method: local_file`。" + } } }, - "InputFileObjectWorkflowCn": { + "InputFileObject": { "type": "object", - "required": ["type", "transfer_method"], + "required": [ + "type", + "transfer_method" + ], "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "文件类型。document: TXT,MD,PDF等; image: JPG,PNG等; audio: MP3,WAV等; video: MP4,MOV等; custom: 其他。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "传递方式，remote_url 用于图片 URL / local_file 用于文件上传" }, - "url": { "type": "string", "format": "url", "description": "图片地址（当传递方式为 remote_url 时）" }, - "upload_file_id": { "type": "string", "description": "上传文件 ID，必须通过事先上传文件接口获得（当传递方式为 local_file 时）" } + "type": { + "type": "string", + "enum": [ + "document", + "image", + "audio", + "video", + "custom" + ], + "description": "文件类型。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件 URL（当 `transfer_method` 为 `remote_url` 时）。" + }, + "upload_file_id": { + "type": "string", + "description": "通过 [上传文件](/api-reference/文件操作/上传文件) API 获取的已上传文件 ID（当 `transfer_method` 为 `local_file` 时使用）。" + } + } + }, + "WorkflowBlockingResponse": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "进行中的执行任务 ID。配合 [停止工作流任务](/api-reference/工作流/停止-工作流-任务) 使用以取消运行中的工作流。仅在执行期间有效。" + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/工作流/获取-工作流-执行情况) 使用以在执行后获取结果。" + }, + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } + } + }, + "ChunkWorkflowEvent": { + "type": "object", + "required": [ + "event" + ], + "properties": { + "event": { + "type": "string", + "enum": [ + "workflow_started", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "text_chunk", + "text_replace", + "workflow_finished", + "tts_message", + "tts_message_end", + "workflow_paused", + "agent_log", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "error", + "ping" + ], + "description": "流式事件的类型。" + } }, - "anyOf": [ + "discriminator": { + "propertyName": "event", + "mapping": { + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "text_chunk": "#/components/schemas/StreamEventTextChunk", + "text_replace": "#/components/schemas/StreamEventTextReplace", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "tts_message": "#/components/schemas/StreamEventTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", + "error": "#/components/schemas/StreamEventError", + "ping": "#/components/schemas/StreamEventPing", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout" + } + } + }, + "StreamEventBase": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "进行中的执行任务 ID。配合 [停止工作流任务](/api-reference/工作流/停止-工作流-任务) 使用以取消运行中的工作流。仅在执行期间有效。" + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/工作流/获取-工作流-执行情况) 使用以在执行后获取结果。" + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工作流运行 ID。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "工作流 ID." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "本次工作流运行的输入变量。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工作流运行开始时的 Unix 时间戳。" + }, + "reason": { + "type": "string", + "description": "工作流启动原因。`initial` 表示新执行，`resumption` 表示从暂停状态恢复。" + } + } + } + } } ] }, - "WorkflowCompletionResponseCn": { - "type": "object", "description": "阻塞模式下的 workflow 执行结果。", - "properties": { - "workflow_run_id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, - "data": { "$ref": "#/components/schemas/WorkflowFinishedDataCn" } - } + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工作流图中的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "节点类型（例如 `llm`、`code`、`template-transform`）。" + }, + "title": { + "type": "string", + "description": "节点的显示名称。" + }, + "index": { + "type": "integer", + "description": "执行序列索引。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID（如有）。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "该节点的输入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是否被截断。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "节点执行开始时的 Unix 时间戳。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "节点执行的附加元数据。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "如果该节点在迭代内运行，则为父迭代 ID。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "如果该节点在循环内运行，则为父循环 ID。" + } + } + } + } + } + ] }, - "ChunkWorkflowEventCn": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["workflow_started", "node_started", "text_chunk", "node_finished", "workflow_finished", "tts_message", "tts_message_end", "ping"], "description": "事件类型。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "workflow_started": "#/components/schemas/StreamEventWfWorkflowStartedCn", "node_started": "#/components/schemas/StreamEventWfNodeStartedCn", - "text_chunk": "#/components/schemas/StreamEventWfTextChunkCn", "node_finished": "#/components/schemas/StreamEventWfNodeFinishedCn", - "workflow_finished": "#/components/schemas/StreamEventWfWorkflowFinishedCn", "tts_message": "#/components/schemas/StreamEventWfTtsMessageCn", - "tts_message_end": "#/components/schemas/StreamEventWfTtsMessageEndCn", "ping": "#/components/schemas/StreamEventWfPingCn" - }} + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工作流图中的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "节点的显示名称。" + }, + "index": { + "type": "integer", + "description": "执行序列索引。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID（如有）。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "该节点的输入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是否被截断。" + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "节点执行期间生成的处理数据。" + }, + "process_data_truncated": { + "type": "boolean", + "description": "`process_data` 是否被截断。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "节点的输出数据。" + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` 数据是否被截断。" + }, + "status": { + "type": "string", + "description": "节点执行状态。`running` 表示进行中，`succeeded` 表示已完成，`failed` 表示出错，`stopped` 表示手动停止，`exception` 表示意外失败。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "节点失败时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "耗时（秒）。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "description": "执行元数据，包含令牌用量。", + "properties": { + "total_tokens": { + "type": "integer", + "nullable": true, + "description": "该节点消耗的总令牌数。" + }, + "total_price": { + "type": "number", + "format": "float", + "nullable": true, + "description": "该节点执行的总费用。" + }, + "currency": { + "type": "string", + "nullable": true, + "description": "费用货币（例如 `USD`）。" + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "节点执行开始时的 Unix 时间戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "节点执行结束时的 Unix 时间戳。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "该节点生成的文件。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "如果该节点在迭代内运行，则为父迭代 ID。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "如果该节点在循环内运行，则为父循环 ID。" + } + } + } + } + } + ] }, - "StreamEventBaseWfCn": { - "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" } } + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工作流图中的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "节点的显示名称。" + }, + "index": { + "type": "integer", + "description": "执行序列索引。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID（如有）。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是否被截断。" + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "节点执行期间生成的处理数据。" + }, + "process_data_truncated": { + "type": "boolean", + "description": "`process_data` 是否被截断。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` 数据是否被截断。" + }, + "status": { + "type": "string", + "description": "重试点的节点执行状态。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "触发重试的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "耗时（秒）。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "retry_index": { + "type": "integer", + "description": "从零开始的重试次数索引。" + }, + "iteration_id": { + "type": "string", + "nullable": true + }, + "loop_id": { + "type": "string", + "nullable": true + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "节点执行的元数据。" + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "节点在执行期间生成的文件。" + } + } + } + } + } + ] }, - "StreamEventWfWorkflowStartedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowStartedDataCn" } } } ] }, - "WorkflowStartedDataCn": { "type": "object", "description": "Workflow 开始执行事件的详细内容。", "required": ["id", "workflow_id", "sequence_number", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "关联 Workflow ID。" }, "sequence_number": { "type": "integer", "description": "自增序号，App 内自增，从 1 开始。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间。" } } }, - "StreamEventWfNodeStartedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeStartedDataCn" } } } ] }, - "NodeStartedDataCn": { "type": "object", "description": "Node 开始执行事件的详细内容。", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID (应为 node 执行 ID，根据上下文修正)。" }, "node_id": { "type": "string", "format": "uuid", "description": "节点 ID。" }, "node_type": { "type": "string", "description": "节点类型。" }, "title": { "type": "string", "description": "节点名称。" }, "index": { "type": "integer", "description": "执行序号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "前置节点 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "节点中所有使用到的前置节点变量内容。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间。" } } }, - "StreamEventWfTextChunkCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/TextChunkDataCn" } } } ] }, - "TextChunkDataCn": { "type": "object", "description": "文本片段事件的详细内容。", "required": ["text", "from_variable_selector"], "properties": { "text": { "type": "string", "description": "文本内容。" }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "description": "文本来源路径，帮助开发者了解文本是由哪个节点的哪个变量生成的。" } } }, - "StreamEventWfNodeFinishedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeFinishedDataCn" } } } ] }, - "NodeFinishedDataCn": { "type": "object", "description": "Node 执行结束事件的详细内容。", "required": ["id", "node_id", "index", "status", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "node 执行 ID。" }, "node_id": { "type": "string", "format": "uuid", "description": "节点 ID。" }, "index": { "type": "integer", "description": "执行序号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "（可选）前置节点 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点中所有使用到的前置节点变量内容。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "（可选）节点过程数据 (JSON)。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "（可选）输出内容 (JSON)。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, "error": { "type": "string", "nullable": true, "description": "（可选）错误原因。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "（可选）耗时(秒)。" }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadataCn" , "nullable": true, "description":"元数据"}, "created_at": { "type": "integer", "format": "int64", "description": "开始时间。" } } }, - "NodeExecutionMetadataCn": { "type": "object", "description": "节点执行元数据。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "（可选）总使用 tokens。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "（可选）总费用 (使用 float 兼容 decimal)。" }, "currency": { "type": "string", "nullable": true, "example": "USD", "description": "（可选）货币，如 USD / RMB。" } } }, - "StreamEventWfWorkflowFinishedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedDataCn" } } } ] }, - "WorkflowFinishedDataCn": { "type": "object", "description": "Workflow 执行结束事件的详细内容。", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "关联 Workflow ID。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "（可选）输出内容 (JSON)。" }, "error": { "type": "string", "nullable": true, "description": "（可选）错误原因。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "（可选）耗时(秒)。" }, "total_tokens": { "type": "integer", "nullable": true, "description": "（可选）总使用 tokens。" }, "total_steps": { "type": "integer", "default": 0, "description": "总步数，默认 0。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间。" }, "finished_at": { "type": "integer", "format": "int64", "description": "结束时间。" } } }, - "StreamEventWfTtsMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "format": "byte", "description": "语音合成之后的音频块 Base64 编码文本。" }, "message_id": { "type": "string", "format": "uuid", "description": "消息唯一 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" } } } ] }, - "StreamEventWfTtsMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "description": "结束事件音频为空字符串。" }, "message_id": { "type": "string", "format": "uuid", "description": "消息唯一 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" } } } ] }, - "StreamEventWfPingCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "type": "object", "description": "每 10s 一次的 ping 事件，保持连接存活。" } ] }, - "WorkflowRunDetailResponseCn": { - "type": "object", "description": "Workflow 执行详情。", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, - "workflow_id": { "type": "string", "format": "uuid", "description": "关联的 Workflow ID。" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, - "inputs": { "type": "string", "description": "任务输入内容的 JSON 字符串。" }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "任务输出内容的 JSON 对象。" }, - "error": { "type": "string", "nullable": true, "description": "错误原因。" }, - "total_steps": { "type": "integer", "description": "任务执行总步数。" }, - "total_tokens": { "type": "integer", "description": "任务执行总 tokens。" }, - "created_at": { "type": "integer", "format": "int64", "description": "任务开始时间。" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "任务结束时间。" }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "耗时(秒)。" } - } + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "迭代节点 ID。" + }, + "node_type": { + "type": "string", + "description": "节点类型（始终为 `iteration`）。" + }, + "title": { + "type": "string", + "description": "迭代节点的显示名称。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "迭代的输入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是否被截断。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "迭代元数据。" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] }, - "FileUploadResponseCn": { "type": "object", "description": "文件上传成功响应。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件大小 (byte)。" }, "extension": { "type": "string", "description": "文件后缀。" }, "mime_type": { "type": "string", "description": "文件 mime-type。" }, "created_by": { "type": "string", "format": "uuid", "description": "上传人 ID (应为 uuid，示例中为 int，已修正)。" }, "created_at": { "type": "integer", "format": "int64", "description": "上传时间。" } } }, - "EndUserDetailCn": { + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "当前迭代索引（从零开始）。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` 数据是否被截断。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "迭代的输入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是否被截断。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "迭代开始时的 Unix 时间戳。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "迭代的附加元数据。" + }, + "status": { + "type": "string", + "description": "迭代完成状态。" + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "执行元数据，包含令牌用量。" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "已完成的迭代步数。" + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是否被截断。" + }, + "metadata": { + "type": "object", + "additionalProperties": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "当前循环迭代索引（从零开始）。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "pre_loop_output": { + "description": "上一次循环迭代的输出。", + "nullable": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` 数据是否被截断。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "循环的输入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是否被截断。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "循环的附加元数据。" + }, + "status": { + "type": "string", + "description": "循环完成状态。" + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "执行元数据，包含令牌用量。" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "已完成的循环迭代次数。" + } + } + } + } + } + ] + }, + "StreamEventTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "文本内容块。" + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "工作流中文本变量的源路径。" + } + } + } + } + } + ] + }, + "StreamEventTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "替换的文本内容。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } + } + } + ] + }, + "StreamEventTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "该音频块生成时的 Unix 时间戳。" + } + } + } + ] + }, + "StreamEventTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "description": "空字符串。标识音频流结束。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "音频流结束时的 Unix 时间戳。" + } + } + } + ] + }, + "StreamEventError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "错误的 HTTP 状态码。" + }, + "code": { + "type": "string", + "description": "错误码。" + }, + "message": { + "type": "string", + "description": "错误信息。" + } + } + } + ] + }, + "StreamEventPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "type": "object", + "description": "保活 ping 事件。无附加属性。" + } + ] + }, + "WorkflowFinishedData": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "工作流运行 ID。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "工作流 ID." + }, + "status": { + "type": "string", + "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "工作流的输出数据。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工作流失败时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时（秒）。" + }, + "total_tokens": { + "type": "integer", + "description": "所有节点消耗的总令牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工作流总步数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工作流运行创建时的 Unix 时间戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工作流运行结束时的 Unix 时间戳。" + }, + "created_by": { + "type": "object", + "additionalProperties": true, + "description": "创建者信息。仅存在于流式 `workflow_finished` 事件中。" + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "执行过程中遇到的异常数量。仅在流式 `workflow_finished` 事件中出现。" + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "nullable": true, + "description": "工作流执行期间生成的文件。仅存在于流式 `workflow_finished` 事件中。" + } } }, - "WorkflowLogsResponseCn": { - "type": "object", "description": "Workflow 日志列表响应。", + "WorkflowRunDetailResponse": { + "type": "object", "properties": { - "page": { "type": "integer", "description": "当前页码。" }, "limit": { "type": "integer", "description": "每页条数。" }, - "total": { "type": "integer", "description": "总条数。" }, "has_more": { "type": "boolean", "description": "是否还有更多数据。" }, - "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowLogItemCn" }, "description": "当前页码的数据。" } + "id": { + "type": "string", + "format": "uuid", + "description": "工作流运行 ID。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "工作流 ID." + }, + "status": { + "type": "string", + "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "工作流运行的输入变量。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "工作流的输出数据。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工作流失败时的错误消息。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工作流总步数。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总令牌数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工作流运行创建时的 Unix 时间戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工作流运行结束时的 Unix 时间戳。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "总耗时（秒）。" + } } }, - "WorkflowLogItemCn": { - "type": "object", "description": "单条 Workflow 日志。", + "FileUploadResponse": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "标识。" }, - "workflow_run": { "$ref": "#/components/schemas/WorkflowRunSummaryCn", "description": "Workflow 执行日志。" }, - "created_from": { "type": "string", "description": "来源。" }, - "created_by_role": { "type": "string", "description": "角色。" }, - "created_by_account": { "type": "string", "format": "uuid", "nullable": true, "description": "（可选）帐号。" }, - "created_by_end_user": { "$ref": "#/components/schemas/EndUserSummaryCn", "description": "用户。" }, - "created_at": { "type": "integer", "format": "int64", "description": "创建时间。" } + "id": { + "type": "string", + "format": "uuid", + "description": "唯一文件 ID。" + }, + "name": { + "type": "string", + "description": "文件名。" + }, + "size": { + "type": "integer", + "description": "文件大小（字节）。" + }, + "extension": { + "type": "string", + "nullable": true, + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "文件的 MIME 类型。" + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "上传文件的用户 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "上传时间戳（Unix 纪元秒）。" + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "文件的预览 URL。" + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "文件的源 URL。" + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "文件的原始 URL。" + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的用户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的租户 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的会话 ID。" + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "文件的存储键。" + } } }, - "WorkflowRunSummaryCn": { - "type": "object", "description": "Workflow 执行摘要信息。", + "EndUserDetail": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "标识。" }, "version": { "type": "string", "description": "版本。" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, - "error": { "type": "string", "nullable": true, "description": "（可选）错误。" }, - "elapsed_time": { "type": "number", "format": "float", "description": "耗时，单位秒。" }, - "total_tokens": { "type": "integer", "description": "消耗的token数量。" }, - "total_steps": { "type": "integer", "description": "执行步骤长度。" }, - "created_at": { "type": "integer", "format": "int64", "description": "开始时间。" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "结束时间。" } + "id": { + "type": "string", + "format": "uuid", + "description": "终端用户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "租户 ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "应用 ID。" + }, + "type": { + "type": "string", + "description": "终端用户类型。Service API 用户固定为 `service_api`。" + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "API 请求中提供的 `user` 标识符（例如 [发送对话消息](/api-reference/对话消息/发送对话消息) 中的 `user` 字段）。" + }, + "name": { + "type": "string", + "nullable": true, + "description": "终端用户名称。" + }, + "is_anonymous": { + "type": "boolean", + "description": "用户是否为匿名用户。当原始 API 请求中未提供 `user` 标识符时，值为 `true`。" + }, + "session_id": { + "type": "string", + "description": "会话标识符。默认为 `external_user_id` 的值。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "创建时间戳。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最后更新时间戳。" + } } }, - "EndUserSummaryCn": { - "type": "object", "description": "终端用户信息摘要。", + "WorkflowLogsResponse": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "标识。" }, "type": { "type": "string", "description": "类型。" }, - "is_anonymous": { "type": "boolean", "description": "是否匿名。" }, "session_id": { "type": "string", "description": "会话标识。" } + "page": { + "type": "integer", + "description": "当前页码。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "日志条目总数。" + }, + "has_more": { + "type": "boolean", + "description": "是否有更多可用页面。" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "工作流日志条目列表。" + } } }, - "AppInfoResponseCn": { "type": "object", "description": "应用基本信息。", "properties": { "name": { "type": "string", "description": "应用名称。" }, "description": { "type": "string", "description": "应用描述。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "应用标签。" } } }, - "WorkflowAppParametersResponseCn": { "type": "object", "description": "Workflow 应用参数信息。", "properties": { "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemCn" }, "description": "用户输入表单配置。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "图片设置。当前仅支持图片类型：png, jpg, jpeg, webp, gif。" } }, "description": "文件上传配置。" }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer", "description": "文档上传大小限制 (MB)。" }, "image_file_size_limit": { "type": "integer", "description": "图片文件上传大小限制（MB）。" }, "audio_file_size_limit": { "type": "integer", "description": "音频文件上传大小限制 (MB)。" }, "video_file_size_limit": { "type": "integer", "description": "视频文件上传大小限制 (MB)。" } }, "description": "系统参数。" } } }, - "UserInputFormItemCn": { "type": "object", "description": "用户输入表单中的控件项。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperCn" }, { "$ref": "#/components/schemas/ParagraphControlWrapperCn" }, { "$ref": "#/components/schemas/SelectControlWrapperCn" } ] }, - "TextInputControlWrapperCn": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlCn" } }, "required":["text-input"] }, - "ParagraphControlWrapperCn": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlCn" } }, "required":["paragraph"] }, - "SelectControlWrapperCn": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlCn" } }, "required":["select"] }, - "TextInputControlCn": { "type": "object", "description": "文本输入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "nullable": true, "description": "默认值。" } } }, - "ParagraphControlCn": { "type": "object", "description": "段落文本输入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "nullable": true, "description": "默认值。" } } }, - "SelectControlCn": { "type": "object", "description": "下拉控件。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "控件展示标签名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是否必填。" }, "default": { "type": "string", "nullable": true, "description": "默认值。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "选项值。" } } }, - "WorkflowWebAppSettingsResponseCn": { "type": "object", "description": "Workflow 应用 WebApp 设置。", "properties": { "title": { "type": "string", "description": "WebApp 名称。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "图标类型。" }, "icon": { "type": "string", "description": "图标内容 (emoji 或图片 URL)。" }, "icon_background": { "type": "string", "description": "hex 格式的背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "图标 URL。" }, "description": { "type": "string", "description": "描述。" }, "copyright": { "type": "string", "description": "版权信息。" }, "privacy_policy": { "type": "string", "description": "隐私政策链接。" }, "custom_disclaimer": { "type": "string", "description": "自定义免责声明。" }, "default_language": { "type": "string", "description": "默认语言。" }, "show_workflow_steps": { "type": "boolean", "description": "是否显示工作流详情。" } } }, - "ErrorResponseCn": { "type": "object", "description": "错误响应。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTP 状态码。" }, "code": { "type": "string", "nullable": true, "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "日志条目 ID。" + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "工作流运行的来源（例如 `service-api`）。" + }, + "created_by_role": { + "type": "string", + "description": "创建者的角色（例如 `end_user`、`account`）。" + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "由管理员用户创建时的账户详情。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "账户 ID。" + }, + "name": { + "type": "string", + "description": "账户显示名称。" + }, + "email": { + "type": "string", + "description": "账户邮箱地址。" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "日志条目创建时的 Unix 时间戳。" + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "日志条目的附加详情。" + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工作流运行 ID。" + }, + "version": { + "type": "string", + "description": "工作流版本标识符。" + }, + "status": { + "type": "string", + "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工作流失败时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时（秒）。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总令牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工作流总步数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工作流运行创建时的 Unix 时间戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工作流运行结束时的 Unix 时间戳。" + }, + "exceptions_count": { + "type": "integer", + "description": "执行期间发生的异常数量。" + }, + "triggered_from": { + "type": "string", + "description": "触发工作流运行的来源。`debugging` 表示从编辑器发起的测试运行，`app` 表示 API 或应用发起的运行。" + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "终端用户 ID。" + }, + "type": { + "type": "string", + "description": "终端用户类型。" + }, + "is_anonymous": { + "type": "boolean", + "description": "终端用户是否为匿名。" + }, + "session_id": { + "type": "string", + "description": "会话标识符。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "语音转文字的请求体。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音频文件。支持格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。大小限制：`30 MB`。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "语音识别输出的文字。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "文字转语音的请求体。提供 `message_id` 或 `text` 其中之一。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。当同时提供 `text` 时，优先使用消息 ID。" + }, + "text": { + "type": "string", + "description": "要转换的语音内容。" + }, + "user": { + "type": "string", + "description": "用户标识符。" + }, + "voice": { + "type": "string", + "description": "文字转语音使用的声音。可用声音取决于为此应用配置的 TTS 提供商。使用[获取应用参数](/api-reference/应用配置/获取应用参数) → `text_to_speech.voice` 中的 `voice` 值作为默认值。" + }, + "streaming": { + "type": "boolean", + "description": "是否启用流式响应。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "应用名称。" + }, + "description": { + "type": "string", + "description": "应用描述。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "应用标签。" + }, + "mode": { + "type": "string", + "description": "应用模式。`completion` 为文本生成应用，`chat` 为基础对话应用，`agent-chat` 为 Agent 应用，`advanced-chat` 为对话流应用，`workflow` 为工作流应用。" + }, + "author_name": { + "type": "string", + "description": "应用作者名称。" + } + } + }, + "WorkflowAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "nullable": true, + "description": "开场白文本。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议问题列表。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答后建议问题的配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "语音转文字功能配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "文字转语音功能配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + }, + "voice": { + "type": "string", + "description": "TTS 声音标识符。" + }, + "language": { + "type": "string", + "description": "TTS 语言。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "知识检索引用资源配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "标注回复功能配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "更多类似推荐功能配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "内容审核功能配置。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用此功能。" + } + } + }, + "user_input_form": { + "type": "array", + "items": { + "type": "object", + "oneOf": [ + { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "输入字段的显示标签。" + }, + "variable": { + "type": "string", + "description": "工作流中使用的变量名称。" + }, + "required": { + "type": "boolean", + "description": "该字段是否必填。" + }, + "default": { + "type": "string", + "description": "输入字段的默认值。" + } + } + } + } + }, + { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "段落字段的显示标签。" + }, + "variable": { + "type": "string", + "description": "工作流中使用的变量名称。" + }, + "required": { + "type": "boolean", + "description": "该字段是否必填。" + }, + "default": { + "type": "string", + "description": "段落字段的默认值。" + } + } + } + } + }, + { + "title": "Select", + "type": "object", + "properties": { + "select": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "下拉选择字段的显示标签。" + }, + "variable": { + "type": "string", + "description": "工作流中使用的变量名称。" + }, + "required": { + "type": "boolean", + "description": "该字段是否必填。" + }, + "default": { + "type": "string", + "description": "默认选中的值。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "此表单控件的可选值列表。" + } + } + } + } + } + ] + }, + "description": "用户输入表单配置。" + }, + "file_upload": { + "type": "object", + "description": "文件上传配置。", + "properties": { + "image": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "是否启用图片上传。" + }, + "number_limits": { + "type": "integer", + "description": "可上传的最大图片数量。" + }, + "detail": { + "type": "string", + "description": "视觉模型的图像细节级别。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "图片上传允许的传输方式。`remote_url` 表示通过文件 URL 上传，`local_file` 表示上传本地文件。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "系统级参数限制。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "常规文件最大大小（MB）。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最大图片文件大小（MB）。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最大音频文件大小（MB）。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最大视频文件大小（MB）。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "每次工作流执行的最大文件数量。" + } + } + } + } + }, + "ToolIconDetail": { + "type": "object", + "properties": { + "background": { + "type": "string", + "description": "工具图标的背景颜色。" + }, + "content": { + "type": "string", + "description": "表情符号或图标内容。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "图标的 URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "工具图标。键为工具名称。" + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp 标题。" + }, + "chat_color_theme": { + "type": "string", + "description": "聊天主题颜色。" + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "聊天主题颜色是否反转。" + }, + "icon_type": { + "type": "string", + "description": "使用的图标类型。`emoji` 为表情图标，`image` 为上传的图片图标。" + }, + "icon": { + "type": "string", + "description": "图标内容（表情或图片 ID）。" + }, + "icon_background": { + "type": "string", + "description": "图标背景颜色。" + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "图标图片的 URL。" + }, + "description": { + "type": "string", + "description": "WebApp 描述。" + }, + "copyright": { + "type": "string", + "description": "版权文本。" + }, + "privacy_policy": { + "type": "string", + "description": "隐私政策 URL。" + }, + "custom_disclaimer": { + "type": "string", + "description": "自定义免责声明文本。" + }, + "default_language": { + "type": "string", + "description": "默认语言代码。" + }, + "show_workflow_steps": { + "type": "boolean", + "description": "是否显示工作流步骤。" + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "是否使用应用图标作为回答图标。" + } + } + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/工作流/获取-工作流-执行情况) 使用以在执行后获取结果。" + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "已暂停的节点 ID 列表。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "暂停时的部分输出。" + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "暂停原因。" + }, + "status": { + "type": "string", + "description": "工作流执行状态。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时间戳。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时（秒）。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总令牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的总步数。" + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "节点执行 ID。" + }, + "id": { + "type": "string", + "description": "Agent 日志条目 ID。" + }, + "label": { + "type": "string", + "description": "Log label." + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "父日志条目 ID。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "Agent 步骤失败时的错误消息。" + }, + "status": { + "type": "string", + "description": "Agent 步骤状态。" + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "Agent 步骤数据。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Agent 步骤元数据。" + }, + "node_id": { + "type": "string", + "description": "Node ID." + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "Form ID." + }, + "node_id": { + "type": "string", + "description": "请求输入的节点 ID。" + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "form_content": { + "type": "string", + "description": "表单内容描述。" + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "表单输入字段定义。" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "可用的用户操作。" + }, + "display_in_ui": { + "type": "boolean", + "description": "是否在 UI 中显示表单。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "表单提交令牌。" + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "表单字段的预解析默认值。" + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "表单过期时的 Unix 时间戳（秒）。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "表单提交后的渲染内容。" + }, + "action_id": { + "type": "string", + "description": "已执行操作的 ID。" + }, + "action_text": { + "type": "string", + "description": "已执行操作的文本。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "表单过期的 Unix 时间戳。" + } + } + } + } + } + ] + } } }, "tags": [ - { "name": "工作流执行", "description": "与执行和管理工作流相关的操作。" }, - { "name": "文件操作 (工作流)", "description": "特定于工作流的文件上传和预览操作。" }, - { "name": "终端用户", "description": "终端用户信息相关的操作。" }, - { "name": "应用配置 (Workflow)", "description": "工作流应用的应用设置和信息。" } + { + "name": "工作流", + "description": "用于执行和管理工作流的操作。" + }, + { + "name": "文件操作", + "description": "文件上传和下载操作。" + }, + { + "name": "终端用户", + "description": "终端用户信息相关操作。" + }, + { + "name": "语音与文字转换", + "description": "语音转文字和文字转语音转换。" + }, + { + "name": "应用配置", + "description": "应用设置、参数和元数据。" + } ] -} \ No newline at end of file +}