{ "openapi": "3.0.1", "info": { "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 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", "description": "Actual base URL of the API" } } } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/chat-messages": { "post": { "summary": "Send Chat Message", "description": "Send a request to the chat application.", "operationId": "sendAdvancedChatMessage", "tags": [ "Chats" ], "requestBody": { "description": "Request body to send a chat message.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" }, "examples": { "streaming_example": { "summary": "Request Example - Streaming mode", "value": { "inputs": { "city": "San Francisco" }, "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", "conversation_id": "", "user": "abc-123", "files": [ { "type": "image", "transfer_method": "remote_url", "url": "https://cloud.dify.ai/logo/logo-site.png" } ] } }, "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" } } } } } }, "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 `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 (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": { "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": "- `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": { "operationId": "uploadAdvancedChatFile", "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": "previewChatFlowFile", "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": "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": "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." } } } } } } } } }, "/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": { "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": { "operationId": "getAdvancedChatAppFeedbacks", "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": "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" } ] } } } } } } } } }, "/conversations": { "get": { "summary": "List Conversations", "description": "Retrieve the conversation list for the current user, ordered by most recently active.", "operationId": "getAdvancedConversationsList", "tags": [ "Conversations" ], "parameters": [ { "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" }, "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." } } } } } } } } }, "/conversations/{conversation_id}": { "delete": { "summary": "Delete Conversation", "description": "Delete a conversation.", "operationId": "deleteAdvancedConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "The user identifier." } } }, "examples": { "deleteExample": { "value": { "user": "abc-123" }, "summary": "Request Example" } } } } }, "responses": { "204": { "description": "Conversation deleted successfully. No content returned." }, "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." } } } } } } } } }, "/audio-to-text": { "post": { "operationId": "advancedAudioToText", "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": "advancedTextToAudio", "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": { "operationId": "getAdvancedChatAppInfo", "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.", "content": { "application/json": { "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" } } } } } } } } }, "/parameters": { "get": { "operationId": "getAdvancedChatAppParameters", "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/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." } } } } } } } } }, "/meta": { "get": { "operationId": "getAdvancedChatAppMeta", "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": { "operationId": "getAdvancedChatWebAppSettings", "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.", "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." } } } } } } } } }, "/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": "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": { "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": "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": "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": [ { "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" }, "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 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": [ { "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 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": "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": [ { "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" }, "examples": { "enableAnnotationReply": { "summary": "Request Example", "value": { "score_threshold": 0.9, "embedding_provider_name": "openai", "embedding_model_name": "text-embedding-3-small" } } } } } }, "responses": { "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": "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" ], "parameters": [ { "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": "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 } ] } } } } } } } } } }, "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": { "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": [ "inputs", "query", "user" ], "properties": { "query": { "type": "string", "description": "User input/question content." }, "inputs": { "type": "object", "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." }, "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": { "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. 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", "description": "Specify a published workflow version ID to execute. If not provided, the latest published version is used." } } }, "ChatCompletionResponse": { "type": "object", "properties": { "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)." } } }, "ChunkChatEvent": { "type": "object", "description": "Base schema for Server-Sent Event chunks in streaming mode.", "properties": { "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/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": "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." } } }, "StreamEventChatMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "answer": { "type": "string", "description": "LLM returned text chunk." } } } ] }, "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": { "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" }, { "type": "object", "description": "TTS audio stream end event.", "properties": { "audio": { "type": "string", "description": "Empty string. Signals the end of the audio stream." } } } ] }, "StreamEventChatMessageFile": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "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." }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID." } } } ] }, "StreamEventChatMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "Message end event, 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" }, "retriever_resources": { "type": "array", "description": "List of retriever resources used.", "items": { "$ref": "#/components/schemas/RetrieverResource" } } } } } } ] }, "StreamEventChatMessageReplace": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "Message content replacement event (e.g., due to content moderation).", "properties": { "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" }, { "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", "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", "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", "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", "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", "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", "description": "List of feedback items.", "items": { "$ref": "#/components/schemas/FeedbackItem" } } } }, "FeedbackItem": { "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", "description": "Result status." }, "data": { "type": "array", "items": { "type": "string" }, "description": "List of suggested questions." } } }, "ConversationHistoryResponse": { "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", "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", "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", "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", "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", "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." } } }, "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", "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 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", "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": "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", "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": { "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": "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." } ] }