{ "openapi": "3.0.1", "info": { "title": "Workflow App API", "description": "Workflow applications offer non-session support and are ideal for translation, article writing, summarization AI, and more.", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", "description": "The base URL for the Workflow App API. Replace {api_base_url} with the actual API base URL.", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", "description": "Actual base URL of the API" } } } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/workflows/run": { "post": { "summary": "Run Workflow", "description": "Execute a workflow. Cannot be executed without a published workflow.", "operationId": "executeWorkflow", "tags": [ "Workflows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { "streaming_example": { "summary": "Request Example - Streaming mode", "value": { "inputs": { "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", "user": "user_workflow_123" } }, "blocking_example": { "summary": "Request Example - Blocking mode", "value": { "inputs": { "query": "Translate this to French: Hello world" }, "response_mode": "blocking", "user": "user_workflow_456" } }, "with_file_array_variable": { "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", "transfer_method": "remote_url", "url": "https://example.com/image.jpg" } ] }, "response_mode": "blocking", "user": "user_workflow_789" } } } } } }, "responses": { "200": { "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" }, "examples": { "blockingResponse": { "summary": "Response Example - Blocking mode", "value": { "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": { "result": "Bonjour le monde" }, "error": null, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630 } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "A stream of Server-Sent Events (SSE).\n\n**Parsing**: Each line begins with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing the JSON, then read the `event` field to determine the event type. Ignore `ping` events, which fire every 10 seconds to keep the connection alive.\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Human Input events**:\n- `human_input_required`: Fires together with `workflow_paused` when the workflow reaches a Human Input node. Use the `form_token` from the payload to drive the form-handling flow via the [Human Input API](/api-reference/human-input/get-human-input-form).\n- `human_input_form_filled`: A recipient submitted the form; workflow execution resumes.\n- `human_input_form_timeout`: The form expired without a response. Workflow follows the timeout fallback edge if defined." }, "examples": { "streamingResponse": { "summary": "Response Example - Streaming mode", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" }, "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"text_input\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Invalid parameter value.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "429": { "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal Server Error." } } } } } } } } }, "/workflows/{workflow_id}/run": { "post": { "summary": "Run Workflow by ID", "description": "Execute a specific workflow version identified by its ID. Useful for running a particular published version of the workflow.", "operationId": "runWorkflowById", "tags": [ "Workflows" ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "description": "Workflow ID of the specific version to execute. This value is returned in the `workflow_id` field of [Run Workflow](/api-reference/workflows/run-workflow) responses and [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { "example": { "summary": "Request Example", "value": { "inputs": { "query": "Summarize this article" }, "response_mode": "blocking", "user": "user_workflow_123" } } } } } }, "responses": { "200": { "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" }, "examples": { "blockingResponse": { "summary": "Response Example - Blocking mode", "value": { "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": { "result": "Article summary here" }, "error": null, "elapsed_time": 2.45, "total_tokens": 280, "total_steps": 4, "created_at": 1705407629, "finished_at": 1705407631 } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "A stream of Server-Sent Events (SSE).\n\n**Parsing**: Each line begins with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing the JSON, then read the `event` field to determine the event type. Ignore `ping` events, which fire every 10 seconds to keep the connection alive.\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Human Input events**:\n- `human_input_required`: Fires together with `workflow_paused` when the workflow reaches a Human Input node. Use the `form_token` from the payload to drive the form-handling flow via the [Human Input API](/api-reference/human-input/get-human-input-form).\n- `human_input_form_filled`: A recipient submitted the form; workflow execution resumes.\n- `human_input_form_timeout`: The form expired without a response. Workflow follows the timeout fallback edge if defined." }, "examples": { "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"text_input\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Required parameter missing or invalid.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Workflow is a draft and cannot be executed." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "404": { "description": "`not_found` : Workflow not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow not found." } } } } } }, "429": { "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal Server Error." } } } } } } } } }, "/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": "getWorkflowRunDetail", "tags": [ "Workflows" ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "description": "Workflow run ID, can be obtained from the workflow execution response or streaming events.", "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": "getWorkflowLogs", "tags": [ "Workflows" ], "parameters": [ { "name": "keyword", "in": "query", "description": "Keyword to search in logs.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by execution status.", "schema": { "type": "string", "enum": [ "succeeded", "failed", "stopped" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination.", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 99999 } }, { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "created_at__before", "in": "query", "description": "Filter logs created before this ISO 8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at__after", "in": "query", "description": "Filter logs created after this ISO 8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_by_end_user_session_id", "in": "query", "description": "Filter by end user session ID.", "schema": { "type": "string" } }, { "name": "created_by_account", "in": "query", "description": "Filter by account ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved workflow logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponse" }, "examples": { "workflowLogs": { "summary": "Response Example", "value": { "page": 1, "limit": 20, "total": 1, "has_more": false, "data": [ { "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", "workflow_run": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "version": "2025-01-16 12:00:00.000000", "status": "succeeded", "error": null, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630, "exceptions_count": 0, "triggered_from": "app" }, "created_from": "service-api", "created_by_role": "end_user", "created_by_account": null, "created_by_end_user": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "type": "service_api", "is_anonymous": false, "session_id": "user_workflow_123" }, "created_at": 1705407629 } ] } } } } } } } } }, "/workflows/tasks/{task_id}/stop": { "post": { "summary": "Stop Workflow Task", "description": "Stop a running workflow task. Only supported in `streaming` mode.", "operationId": "stopWorkflowTaskGeneration", "tags": [ "Workflows" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "Task ID, can be obtained from the streaming chunk return of the [Run Workflow](/api-reference/workflows/run-workflow) API.", "schema": { "type": "string" } } ], "requestBody": { "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 [Run Workflow](/api-reference/workflows/run-workflow) request." } } }, "examples": { "example": { "summary": "Request Example", "value": { "user": "user_workflow_123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `invalid_param` : Required parameter missing or invalid.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } } } } }, "/files/upload": { "post": { "operationId": "uploadWorkflowFile", "tags": [ "Files" ], "summary": "Upload File", "description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", "requestBody": { "description": "File upload request. Requires multipart/form-data.", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to be uploaded. Supported types include images, documents, audio, and video." }, "user": { "type": "string", "description": "User identifier, defined by the developer's rules, must be unique within the application." } } } } } }, "responses": { "201": { "description": "File 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": "downloadWorkflowFile", "tags": [ "Files" ], "summary": "Download File", "description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.", "schema": { "type": "string", "format": "uuid" } }, { "name": "as_attachment", "in": "query", "required": false, "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", "schema": { "type": "boolean", "default": false } }, { "name": "user", "in": "query", "required": false, "description": "User identifier, used for end-user context.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "`file_access_denied` : Access to the requested file is denied.", "content": { "application/json": { "examples": { "file_access_denied": { "summary": "file_access_denied", "value": { "status": 403, "code": "file_access_denied", "message": "Access to the requested file is denied." } } } } } }, "404": { "description": "`file_not_found` : The requested file was not found.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "status": 404, "code": "file_not_found", "message": "The requested file was not found." } } } } } } } } }, "/end-users/{end_user_id}": { "get": { "operationId": "getEndUserWorkflow", "tags": [ "End Users" ], "summary": "Get End User Info", "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).", "parameters": [ { "name": "end_user_id", "in": "path", "required": true, "description": "End user ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "End user retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserDetail" }, "examples": { "endUserDetail": { "summary": "Response Example", "value": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "type": "service_api", "external_user_id": "abc-123", "name": null, "is_anonymous": false, "session_id": "abc-123", "created_at": "2024-01-16T12:00:29Z", "updated_at": "2024-01-16T12:00:29Z" } } } } } }, "404": { "description": "`end_user_not_found` : End user not found.", "content": { "application/json": { "examples": { "end_user_not_found": { "summary": "end_user_not_found", "value": { "status": 404, "code": "end_user_not_found", "message": "End user not found." } } } } } } } } }, "/audio-to-text": { "post": { "operationId": "workflowAudioToText", "tags": [ "TTS" ], "summary": "Convert Audio to Text", "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequest" } } } }, "responses": { "200": { "description": "Successfully converted audio to text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponse" }, "examples": { "audioToTextSuccess": { "summary": "Response Example", "value": { "text": "Hello, I would like to know more about the iPhone 13 Pro Max." } } } } } }, "400": { "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "no_audio_uploaded": { "summary": "no_audio_uploaded", "value": { "status": 400, "code": "no_audio_uploaded", "message": "Please upload your audio." } }, "provider_not_support_speech_to_text": { "summary": "provider_not_support_speech_to_text", "value": { "status": 400, "code": "provider_not_support_speech_to_text", "message": "Provider not support speech to text." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "413": { "description": "`audio_too_large` : Audio file size exceeded the limit.", "content": { "application/json": { "examples": { "audio_too_large": { "summary": "audio_too_large", "value": { "status": 413, "code": "audio_too_large", "message": "Audio size exceeded." } } } } } }, "415": { "description": "`unsupported_audio_type` : Audio type is not allowed.", "content": { "application/json": { "examples": { "unsupported_audio_type": { "summary": "unsupported_audio_type", "value": { "status": 415, "code": "unsupported_audio_type", "message": "Audio type not allowed." } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal server error." } } } } } } } } }, "/text-to-audio": { "post": { "operationId": "workflowTextToAudio", "tags": [ "TTS" ], "summary": "Convert Text to Audio", "description": "Convert text to speech.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToAudioRequest" }, "examples": { "textToAudioExample": { "summary": "Request Example", "value": { "text": "Hello, welcome to our service.", "user": "abc-123", "voice": "alloy", "streaming": false } } } } } }, "responses": { "200": { "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal server error." } } } } } } } } }, "/info": { "get": { "operationId": "getWorkflowAppInfo", "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 Workflow App", "description": "A helpful customer service chatbot.", "tags": [ "customer-service", "chatbot" ], "mode": "workflow", "author_name": "Dify Team" } } } } } } } } }, "/parameters": { "get": { "operationId": "getWorkflowAppParameters", "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/WorkflowAppParametersResponse" }, "examples": { "appParameters": { "summary": "Response Example", "value": { "opening_statement": "Hello! How can I help you today?", "suggested_questions": [ "What can you do?", "Tell me about your features." ], "suggested_questions_after_answer": { "enabled": true }, "speech_to_text": { "enabled": false }, "text_to_speech": { "enabled": false, "voice": "alloy", "language": "en-US", "autoPlay": "disabled" }, "retriever_resource": { "enabled": true }, "annotation_reply": { "enabled": false }, "more_like_this": { "enabled": false }, "sensitive_word_avoidance": { "enabled": false }, "user_input_form": [ { "text-input": { "label": "City", "variable": "city", "required": true, "default": "" } } ], "file_upload": { "image": { "enabled": true, "number_limits": 3, "detail": "high", "transfer_methods": [ "remote_url", "local_file" ] } }, "system_parameters": { "file_size_limit": 15, "image_file_size_limit": 10, "audio_file_size_limit": 50, "video_file_size_limit": 100, "workflow_file_upload_limit": 10 } } } } } } }, "400": { "description": "`app_unavailable` : App unavailable or misconfigured.", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } } } } } } } } }, "/meta": { "get": { "operationId": "getWorkflowAppMeta", "tags": [ "Applications" ], "summary": "Get App Meta", "description": "Retrieve metadata about this application, including tool icons and other configuration details.", "responses": { "200": { "description": "Successfully retrieved application meta information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponse" }, "examples": { "appMeta": { "summary": "Response Example", "value": { "tool_icons": { "dalle3": "https://example.com/icons/dalle3.png", "calculator": { "background": "#4A90D9", "content": "🧮" } } } } } } } } } } }, "/site": { "get": { "operationId": "getWorkflowWebAppSettings", "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." } } } } } } } } }, "/form/human_input/{form_token}": { "get": { "tags": [ "Human Input" ], "summary": "Get Human Input Form", "description": "Retrieve a paused Human Input form's contents using the `form_token` from a `human_input_required` event. Requires **WebApp** delivery.", "operationId": "getWorkflowHumanInputForm", "parameters": [ { "name": "form_token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Access token for the paused form, returned in the `human_input_required` event from [Run Workflow](/api-reference/workflows/run-workflow) in streaming mode." } ], "responses": { "200": { "description": "Form contents retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "form_content": { "type": "string", "description": "Pre-rendered form body with workflow variables substituted." }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Form input control type. Available values: `text_input` (single-line text field) and `paragraph` (multi-line text area)." }, "output_variable_name": { "type": "string", "description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object." }, "default": { "type": "object", "nullable": true, "description": "Default value resolved from the workflow context. `null` when no default is configured.", "properties": { "type": { "type": "string", "description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable." }, "selector": { "type": "array", "items": { "type": "string" }, "description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements." }, "value": { "type": "string", "description": "Literal default value when `type` is `constant`. Always a string." } } } } }, "description": "Form input field definitions." }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Pre-filled default values, keyed by input `output_variable_name`. All values are stringified." }, "user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Identifier of the action button. Pass as `action` on [Submit Human Input Form](/api-reference/human-input/submit-human-input-form) when the recipient selects this button." }, "title": { "type": "string", "maxLength": 100, "description": "Button label shown to the recipient." }, "button_style": { "type": "string", "description": "Visual style of the button. Available values: `primary`, `default`, `accent`, `ghost`." } } }, "description": "Available submission actions." }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) after which this form can no longer be submitted." } } }, "examples": { "success": { "summary": "Response Example", "value": { "form_content": "Please review the draft and confirm or request changes.", "inputs": [ { "type": "text_input", "output_variable_name": "comment", "default": { "type": "constant", "selector": [], "value": "" } } ], "resolved_default_values": { "comment": "" }, "user_actions": [ { "id": "approve", "title": "Approve", "button_style": "primary" }, { "id": "reject", "title": "Request changes", "button_style": "default" } ], "expiration_time": 1745510400 } } } } } }, "404": { "description": "`not_found` : Form not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Form not found" } } } } } }, "412": { "description": "- `human_input_form_submitted` : Form already submitted. Forms are one-shot; the first response wins regardless of which user submits it.\n- `human_input_form_expired` : The form's expiration time passed before submission arrived.", "content": { "application/json": { "examples": { "human_input_form_submitted": { "summary": "human_input_form_submitted", "value": { "status": 412, "code": "human_input_form_submitted", "message": "This form has already been submitted by another user, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "human_input_form_expired": { "summary": "human_input_form_expired", "value": { "status": 412, "code": "human_input_form_expired", "message": "This form has expired, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } } }, "post": { "tags": [ "Human Input" ], "summary": "Submit Human Input Form", "description": "Submit the recipient's response to a paused Human Input form. The workflow resumes on acceptance; use [Stream Workflow Events](/api-reference/workflows/stream-workflow-events) to follow subsequent events. Requires **WebApp** delivery.", "operationId": "submitWorkflowHumanInputForm", "parameters": [ { "name": "form_token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Access token for the paused form, returned in the `human_input_required` event from [Run Workflow](/api-reference/workflows/run-workflow) in streaming mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs", "action", "user" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "Recipient-supplied values keyed by input `output_variable_name`." }, "action": { "type": "string", "description": "ID of the action button the recipient selected. Must match one of the `id` values from the form's `user_actions` list (returned by [Get Human Input Form](/api-reference/human-input/get-human-input-form)).", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "user": { "type": "string", "description": "End-user identifier for the submitter." } } }, "examples": { "approve": { "summary": "Request Example", "value": { "inputs": { "comment": "Looks good to ship" }, "action": "approve", "user": "abc-123" } } } } } }, "responses": { "200": { "description": "Form submitted successfully. The response body is an empty object.", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "success": { "summary": "Response Example", "value": {} } } } } }, "400": { "description": "- `bad_request` : Form recipient type is invalid.\n- `invalid_form_data` : Submission failed validation against the form definition.", "content": { "application/json": { "examples": { "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Form recipient type is invalid" } }, "invalid_form_data": { "summary": "invalid_form_data", "value": { "status": 400, "code": "invalid_form_data", "message": "Missing required inputs: comment" } } } } } }, "404": { "description": "`not_found` : Form not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Form not found" } } } } } }, "412": { "description": "- `human_input_form_submitted` : Form already submitted. Forms are one-shot; the first response wins regardless of which user submits it.\n- `human_input_form_expired` : The form's expiration time passed before submission arrived.", "content": { "application/json": { "examples": { "human_input_form_submitted": { "summary": "human_input_form_submitted", "value": { "status": 412, "code": "human_input_form_submitted", "message": "This form has already been submitted by another user, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "human_input_form_expired": { "summary": "human_input_form_expired", "value": { "status": 412, "code": "human_input_form_expired", "message": "This form has expired, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } } } }, "/workflow/{task_id}/events": { "get": { "tags": [ "Workflows" ], "summary": "Stream Workflow Events", "description": "Resume the Server-Sent Events stream for a workflow run after a pause or a dropped SSE connection. For runs that have already finished, the stream emits a single `workflow_finished` event and closes.", "operationId": "streamWorkflowEvents", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workflow run ID returned by the original workflow run request." }, { "name": "user", "in": "query", "required": true, "schema": { "type": "string" }, "description": "End-user identifier that originally triggered the run. Must match the creator of the workflow run." }, { "name": "include_state_snapshot", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When `true`, replay from the persisted state snapshot to include a status summary of already-executed nodes before streaming new events." }, { "name": "continue_on_pause", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Set to `true` to keep the stream open across multiple `workflow_paused` events (useful when the workflow has more than one Human Input node in sequence). Default closes the stream after the first pause." } ], "responses": { "200": { "description": "Server-Sent Events stream. Each event is delivered as `data: {JSON}\\n\\n`. Event payloads follow the same schemas as the original streaming response.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE stream of workflow events." } } } }, "400": { "description": "`not_workflow_app` : Please check if your app mode matches the right 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": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow run not found" } } } } } } } } } }, "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", "enum": [ "success" ], "description": "Operation result." } } }, "examples": { "success": { "summary": "Response Example", "value": { "result": "success" } } } } } } }, "schemas": { "WorkflowExecutionRequest": { "type": "object", "required": [ "inputs", "user" ], "properties": { "inputs": { "type": "object", "description": "Key-value pairs for workflow input variables. Values for file-type variables should be arrays of file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" } } ] } }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events. When omitted, defaults to blocking behavior." }, "user": { "type": "string", "description": "User identifier, defined by the developer's rules, must be unique within the application. This identifier scopes data access — workflow runs and files are only visible when queried with the same `user` value." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, "nullable": true, "description": "File list. Suitable when files need to be combined with text for input, available only when the model supports Vision capability. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`." } } }, "InputFileObject": { "type": "object", "required": [ "type", "transfer_method" ], "properties": { "type": { "type": "string", "enum": [ "document", "image", "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 (when `transfer_method` is `remote_url`)." }, "upload_file_id": { "type": "string", "description": "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (when `transfer_method` is `local_file`)." } } }, "WorkflowBlockingResponse": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/api-reference/workflows/stop-workflow-task) to cancel a running workflow. Only valid during execution." }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." }, "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } }, "ChunkWorkflowEvent": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "The type of streaming event.", "enum": [ "workflow_started", "node_started", "node_finished", "node_retry", "iteration_started", "iteration_next", "iteration_completed", "loop_started", "loop_next", "loop_completed", "text_chunk", "text_replace", "workflow_finished", "tts_message", "tts_message_end", "workflow_paused", "agent_log", "human_input_required", "human_input_form_filled", "human_input_form_timeout", "error", "ping" ] } }, "discriminator": { "propertyName": "event", "mapping": { "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", "node_started": "#/components/schemas/StreamEventNodeStarted", "node_finished": "#/components/schemas/StreamEventNodeFinished", "node_retry": "#/components/schemas/StreamEventNodeRetry", "iteration_started": "#/components/schemas/StreamEventIterationStarted", "iteration_next": "#/components/schemas/StreamEventIterationNext", "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", "loop_started": "#/components/schemas/StreamEventLoopStarted", "loop_next": "#/components/schemas/StreamEventLoopNext", "loop_completed": "#/components/schemas/StreamEventLoopCompleted", "text_chunk": "#/components/schemas/StreamEventTextChunk", "text_replace": "#/components/schemas/StreamEventTextReplace", "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", "tts_message": "#/components/schemas/StreamEventTtsMessage", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", "error": "#/components/schemas/StreamEventError", "ping": "#/components/schemas/StreamEventPing", "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", "agent_log": "#/components/schemas/StreamEventAgentLog", "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout" } } }, "StreamEventBase": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/api-reference/workflows/stop-workflow-task) to cancel a running workflow. Only valid during execution." }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." } } }, "StreamEventWorkflowStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Workflow run ID." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Workflow ID." }, "inputs": { "type": "object", "additionalProperties": true, "description": "Input variables for this workflow run." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the workflow run started." }, "reason": { "type": "string", "description": "Reason for the workflow start. `initial` for a new execution, `resumption` when resuming from a paused state." } } } } } ] }, "StreamEventNodeStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Node execution ID." }, "node_id": { "type": "string", "description": "Node ID in the workflow graph." }, "node_type": { "type": "string", "description": "Node type (e.g., `llm`, `code`, `template-transform`)." }, "title": { "type": "string", "description": "Display name of the node." }, "index": { "type": "integer", "description": "Execution sequence index." }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "ID of the predecessor node, if any." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Input variables for this node." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the node execution started." }, "extras": { "type": "object", "additionalProperties": true, "description": "Additional metadata for the node execution." }, "iteration_id": { "type": "string", "nullable": true, "description": "Parent iteration ID if this node runs inside an iteration." }, "loop_id": { "type": "string", "nullable": true, "description": "Parent loop ID if this node runs inside a loop." } } } } } ] }, "StreamEventNodeFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Node execution ID." }, "node_id": { "type": "string", "description": "Node ID in the workflow graph." }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "Display name of the node." }, "index": { "type": "integer", "description": "Execution sequence index." }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "ID of the predecessor node, if any." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Input variables for this node." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Processing data generated during node execution." }, "process_data_truncated": { "type": "boolean", "description": "Whether the `process_data` was truncated." }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output data from the node." }, "outputs_truncated": { "type": "boolean", "description": "Whether the `outputs` data was truncated." }, "status": { "type": "string", "description": "Node execution status. `running` for in-progress, `succeeded` when completed, `failed` on error, `stopped` when manually halted, `exception` on unexpected failure." }, "error": { "type": "string", "nullable": true, "description": "Error message if the node failed." }, "elapsed_time": { "type": "number", "format": "float", "description": "Time elapsed in seconds." }, "execution_metadata": { "type": "object", "nullable": true, "description": "Execution metadata including token usage.", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "Total tokens consumed by this node." }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "Total cost for this node execution." }, "currency": { "type": "string", "nullable": true, "description": "Currency of the cost (e.g., `USD`)." } } }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the node execution started." }, "finished_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the node execution finished." }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "Files generated by this node." }, "iteration_id": { "type": "string", "nullable": true, "description": "Parent iteration ID if this node runs inside an iteration." }, "loop_id": { "type": "string", "nullable": true, "description": "Parent loop ID if this node runs inside a loop." } } } } } ] }, "StreamEventNodeRetry": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Node execution ID." }, "node_id": { "type": "string", "description": "Node ID in the workflow graph." }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "Display name of the node." }, "index": { "type": "integer", "description": "Execution sequence index." }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "ID of the predecessor node, if any." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Processing data generated during node execution." }, "process_data_truncated": { "type": "boolean", "description": "Whether the `process_data` was truncated." }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "Whether the `outputs` data was truncated." }, "status": { "type": "string", "description": "Node execution status at the retry point." }, "error": { "type": "string", "nullable": true, "description": "Error message that triggered the retry." }, "elapsed_time": { "type": "number", "format": "float", "description": "Time elapsed in seconds." }, "created_at": { "type": "integer", "format": "int64" }, "finished_at": { "type": "integer", "format": "int64" }, "retry_index": { "type": "integer", "description": "Zero-based retry attempt index." }, "iteration_id": { "type": "string", "nullable": true }, "loop_id": { "type": "string", "nullable": true }, "execution_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Metadata from the node execution." }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Files produced by the node during execution." } } } } } ] }, "StreamEventIterationStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Node execution ID." }, "node_id": { "type": "string", "description": "Iteration node ID." }, "node_type": { "type": "string", "description": "Node type (always `iteration`)." }, "title": { "type": "string", "description": "Display name of the iteration node." }, "created_at": { "type": "integer", "format": "int64" }, "inputs": { "type": "object", "additionalProperties": true, "description": "Input variables for the iteration." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Iteration metadata." }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "StreamEventIterationNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer", "description": "Current iteration index (zero-based)." }, "created_at": { "type": "integer", "format": "int64" }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "StreamEventIterationCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "Whether the `outputs` data was truncated." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Input variables for the iteration." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the iteration started." }, "extras": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Additional metadata for the iteration." }, "status": { "type": "string", "description": "Iteration completion status." }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float" }, "total_tokens": { "type": "integer" }, "execution_metadata": { "type": "object", "additionalProperties": true, "description": "Execution metadata including token usage." }, "finished_at": { "type": "integer", "format": "int64" }, "steps": { "type": "integer", "description": "Number of iteration steps completed." } } } } } ] }, "StreamEventLoopStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "created_at": { "type": "integer", "format": "int64" }, "inputs": { "type": "object", "additionalProperties": true }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "metadata": { "type": "object", "additionalProperties": true }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "StreamEventLoopNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer", "description": "Current loop iteration index (zero-based)." }, "created_at": { "type": "integer", "format": "int64" }, "pre_loop_output": { "description": "Output from the previous loop iteration.", "nullable": true }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "StreamEventLoopCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "Whether the `outputs` data was truncated." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Input variables for the loop." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "created_at": { "type": "integer", "format": "int64" }, "extras": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Additional metadata for the loop." }, "status": { "type": "string", "description": "Loop completion status." }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float" }, "total_tokens": { "type": "integer" }, "execution_metadata": { "type": "object", "additionalProperties": true, "description": "Execution metadata including token usage." }, "finished_at": { "type": "integer", "format": "int64" }, "steps": { "type": "integer", "description": "Number of loop iterations completed." } } } } } ] }, "StreamEventTextChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string", "description": "The text content chunk." }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Source path of the text variable in the workflow." } } } } } ] }, "StreamEventTextReplace": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string", "description": "The replacement text content." } } } } } ] }, "StreamEventWorkflowFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } } ] }, "StreamEventTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when this audio chunk was generated." } } } ] }, "StreamEventTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "audio": { "type": "string", "description": "Empty string. Signals the end of the audio stream." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the audio stream ended." } } } ] }, "StreamEventError": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status code of the error." }, "code": { "type": "string", "description": "Error code." }, "message": { "type": "string", "description": "Error message." } } } ] }, "StreamEventPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "type": "object", "description": "Keep-alive ping event. No additional properties." } ] }, "WorkflowFinishedData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Workflow run ID." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Workflow ID." }, "status": { "type": "string", "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output data from the workflow." }, "error": { "type": "string", "nullable": true, "description": "Error message if the workflow failed." }, "elapsed_time": { "type": "number", "format": "float", "description": "Total time elapsed in seconds." }, "total_tokens": { "type": "integer", "description": "Total tokens consumed across all nodes." }, "total_steps": { "type": "integer", "description": "Total number of workflow steps executed." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the workflow run was created." }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp of when the workflow run finished." }, "created_by": { "type": "object", "additionalProperties": true, "description": "Creator information. Only present in streaming `workflow_finished` events." }, "exceptions_count": { "type": "integer", "nullable": true, "description": "Number of exceptions encountered during execution. Only present in streaming `workflow_finished` events." }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true, "description": "Files generated during workflow execution. Only present in streaming `workflow_finished` events." } } }, "WorkflowRunDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Workflow run ID." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Workflow ID." }, "status": { "type": "string", "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." }, "inputs": { "type": "object", "additionalProperties": true, "description": "Input variables for the workflow run." }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output data from the workflow." }, "error": { "type": "string", "nullable": true, "description": "Error message if the workflow failed." }, "total_steps": { "type": "integer", "description": "Total number of workflow steps executed." }, "total_tokens": { "type": "integer", "description": "Total tokens consumed." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the workflow run was created." }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp of when the workflow run finished." }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "Total time elapsed in seconds." } } }, "FileUploadResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "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." } } }, "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." } } }, "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." } } }, "WorkflowAppParametersResponse": { "type": "object", "properties": { "opening_statement": { "type": "string", "nullable": true, "description": "Opening statement text." }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "List of suggested questions." }, "suggested_questions_after_answer": { "type": "object", "description": "Configuration for suggested questions after an answer.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "speech_to_text": { "type": "object", "description": "Speech-to-text feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "text_to_speech": { "type": "object", "description": "Text-to-speech feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." }, "voice": { "type": "string", "description": "Voice identifier for TTS." }, "language": { "type": "string", "description": "Language for TTS." } } }, "retriever_resource": { "type": "object", "description": "Knowledge retrieval citation resource configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "annotation_reply": { "type": "object", "description": "Annotation reply feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "more_like_this": { "type": "object", "description": "More-like-this feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "sensitive_word_avoidance": { "type": "object", "description": "Content moderation feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "user_input_form": { "type": "array", "items": { "type": "object", "oneOf": [ { "title": "Text Input", "type": "object", "properties": { "text-input": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the input field." }, "variable": { "type": "string", "description": "Variable name used in the workflow." }, "required": { "type": "boolean", "description": "Whether this field is required." }, "default": { "type": "string", "description": "Default value for the input field." } } } } }, { "title": "Paragraph", "type": "object", "properties": { "paragraph": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the paragraph field." }, "variable": { "type": "string", "description": "Variable name used in the workflow." }, "required": { "type": "boolean", "description": "Whether this field is required." }, "default": { "type": "string", "description": "Default value for the paragraph field." } } } } }, { "title": "Select", "type": "object", "properties": { "select": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the select field." }, "variable": { "type": "string", "description": "Variable name used in the workflow." }, "required": { "type": "boolean", "description": "Whether this field is required." }, "default": { "type": "string", "description": "Default selected value." }, "options": { "type": "array", "items": { "type": "string" }, "description": "List of selectable values for this form control." } } } } } ] }, "description": "User input form configuration." }, "file_upload": { "type": "object", "description": "File upload configuration.", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether image upload is enabled." }, "number_limits": { "type": "integer", "description": "Maximum number of images that can be uploaded." }, "detail": { "type": "string", "description": "Image detail level for vision models." }, "transfer_methods": { "type": "array", "items": { "type": "string" }, "description": "Allowed transfer methods for image upload. `remote_url` for file URL, `local_file` for uploaded file." } } } } }, "system_parameters": { "type": "object", "description": "System-level parameter limits.", "properties": { "file_size_limit": { "type": "integer", "description": "Maximum general file size in MB." }, "image_file_size_limit": { "type": "integer", "description": "Maximum image file size in MB." }, "audio_file_size_limit": { "type": "integer", "description": "Maximum audio file size in MB." }, "video_file_size_limit": { "type": "integer", "description": "Maximum video file size in MB." }, "workflow_file_upload_limit": { "type": "integer", "description": "Maximum number of files per workflow execution." } } } } }, "ToolIconDetail": { "type": "object", "properties": { "background": { "type": "string", "description": "Background color of the tool icon." }, "content": { "type": "string", "description": "Emoji or icon content." } } }, "AppMetaResponse": { "type": "object", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "title": "Icon URL", "type": "string", "format": "url", "description": "URL of the icon." }, { "$ref": "#/components/schemas/ToolIconDetail" } ] }, "description": "Tool icons. Keys are tool names." } } }, "WebAppSettingsResponse": { "type": "object", "properties": { "title": { "type": "string", "description": "WebApp title." }, "chat_color_theme": { "type": "string", "description": "Chat color theme." }, "chat_color_theme_inverted": { "type": "boolean", "description": "Whether the chat color theme is inverted." }, "icon_type": { "type": "string", "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." }, "icon": { "type": "string", "description": "Icon content (emoji or image ID)." }, "icon_background": { "type": "string", "description": "Icon background color." }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "URL of the icon image." }, "description": { "type": "string", "description": "WebApp description." }, "copyright": { "type": "string", "description": "Copyright text." }, "privacy_policy": { "type": "string", "description": "Privacy policy URL." }, "custom_disclaimer": { "type": "string", "description": "Custom disclaimer text." }, "default_language": { "type": "string", "description": "Default language code." }, "show_workflow_steps": { "type": "boolean", "description": "Whether to show workflow steps." }, "use_icon_as_answer_icon": { "type": "boolean", "description": "Whether to use the app icon as the answer icon." } } }, "StreamEventWorkflowPaused": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid", "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." }, "paused_nodes": { "type": "array", "items": { "type": "string" }, "description": "List of paused node IDs." }, "outputs": { "type": "object", "additionalProperties": true, "description": "Partial outputs at pause time." }, "reasons": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Reasons for pausing." }, "status": { "type": "string", "description": "Workflow execution status." }, "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." }, "elapsed_time": { "type": "number", "format": "float", "description": "Total elapsed time in seconds." }, "total_tokens": { "type": "integer", "description": "Total tokens consumed." }, "total_steps": { "type": "integer", "description": "Total steps executed." } } } } } ] }, "StreamEventAgentLog": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_execution_id": { "type": "string", "description": "Node execution ID." }, "id": { "type": "string", "description": "Agent log entry ID." }, "label": { "type": "string", "description": "Log label." }, "parent_id": { "type": "string", "nullable": true, "description": "Parent log entry ID." }, "error": { "type": "string", "nullable": true, "description": "Error message if the agent step failed." }, "status": { "type": "string", "description": "Agent step status." }, "data": { "type": "object", "additionalProperties": true, "description": "Agent step data." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Agent step metadata." }, "node_id": { "type": "string", "description": "Node ID." } } } } } ] }, "StreamEventHumanInputRequired": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "form_id": { "type": "string", "description": "Identifier for the form instance, surfaced in error messages and logs. Use `form_token` for Service API calls." }, "node_id": { "type": "string", "description": "ID of the Human Input node that produced this form." }, "node_title": { "type": "string", "description": "Display title of the Human Input node." }, "form_content": { "type": "string", "description": "Pre-rendered form body with workflow variables substituted." }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Form input control type. Available values: `text_input` (single-line text field) and `paragraph` (multi-line text area)." }, "output_variable_name": { "type": "string", "description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object." }, "default": { "type": "object", "nullable": true, "description": "Default value resolved from the workflow context. `null` when no default is configured.", "properties": { "type": { "type": "string", "description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable." }, "selector": { "type": "array", "items": { "type": "string" }, "description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements." }, "value": { "type": "string", "description": "Literal default value when `type` is `constant`. Always a string." } } } } }, "description": "Form input fields the recipient fills in." }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Identifier of the action button. Pass as `action` on [Submit Human Input Form](/api-reference/human-input/submit-human-input-form) when the recipient selects this button." }, "title": { "type": "string", "maxLength": 100, "description": "Button label shown to the recipient." }, "button_style": { "type": "string", "description": "Visual style of the button. Available values: `primary`, `default`, `accent`, `ghost`." } } }, "description": "Available user actions (buttons) the recipient can select when submitting." }, "display_in_ui": { "type": "boolean", "description": "Whether the form is also shown in the Dify console UI." }, "form_token": { "type": "string", "nullable": true, "description": "Access token for [Get Human Input Form](/api-reference/human-input/get-human-input-form) and [Submit Human Input Form](/api-reference/human-input/submit-human-input-form). `null` when the Human Input node uses Email or Console delivery (the Service API can only operate on WebApp-delivered forms)." }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Pre-filled default values for the form inputs, keyed by input `output_variable_name`. All values are stringified." }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) after which the form can no longer be submitted." } } } } } ] }, "StreamEventHumanInputFormFilled": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "ID of the Human Input node whose form was filled." }, "node_title": { "type": "string", "description": "Display title of the Human Input node." }, "rendered_content": { "type": "string", "description": "Form body rendered with the recipient's submitted values (`form_content` on `human_input_required` is the unfilled template)." }, "action_id": { "type": "string", "description": "Identifier of the action the recipient selected (matches the `action` value passed to [Submit Human Input Form](/api-reference/human-input/submit-human-input-form))." }, "action_text": { "type": "string", "description": "Display text of the selected action." } } } } } ] }, "StreamEventHumanInputFormTimeout": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "ID of the Human Input node whose form expired." }, "node_title": { "type": "string", "description": "Display title of the Human Input node." }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the form expired." } } } } } ] } } }, "tags": [ { "name": "Workflows", "description": "Operations for executing and managing workflows." }, { "name": "Files", "description": "File upload and download operations." }, { "name": "End Users", "description": "Operations related to end user information." }, { "name": "TTS", "description": "Audio-to-text and text-to-audio conversion." }, { "name": "Applications", "description": "Application settings, parameters, and metadata." }, { "name": "Human Input", "description": "Endpoints for resuming paused workflows that require human input." } ] }