centersl/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-03-27 13:28:32 +07:00
Code Issues Packages Projects Releases Wiki Activity
Files
21122c4282c5730d54cefde9066367cd37eaaf62
dify-docs/en/api-reference/openapi_chatflow.json
Riskey 21122c4282 Batch update apis (#715) 
* Batch update service apis

* final check and add zh/ja docs

* add temporary redirects for changed api links embedded in the product

* Restore original operationIds to preserve SDK compatibility

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* complete the missing descriptions

* correct the human input terminology

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23 16:38:10 +08:00

6208 lines
212 KiB
JSON
Raw Blame History

{
"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."
}
]
}
Reference in New Issue View Git Blame Copy Permalink