langgenius/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-07-24 04:25:07 -04:00
Code Issues 10 Packages Projects Releases Wiki Activity
Files
6258bbfb0f653f3caaa06fae84207c82041b0ac8
dify-docs/en/api-reference/openapi_workflow.json
T
Riskey 32e1b169da feat: consolidate and restructure the API reference (Phase 1) (#846) 
* docs: correct HITL API integration flow and sync translations

- Fix the claim that the resume endpoint differs per app type (same
  endpoint; only the entry endpoint differs)
- Tie workflow_run_id guidance to the human_input_required event
  (chatflow message chunks don't carry it)
- Require the same user when resuming the event stream (mismatch
  returns 404); add include_state_snapshot and continue_on_pause
  guidance
- Note at the capture step that a null form_token means Email delivery
- Soften the upload-time validation claim to file size limits
- Split long paragraphs; align zh endpoint name with the reference page

* fix: correct API references against verified backend behavior

Audit of the Service API specs against dify hotfix/1.15.0-fix.1, with
every change code-verified and the serious items adversarially
confirmed. Applies to en/zh/ja.

- Add curl samples for GET endpoints with required query params
  (Mintlify omits query params from generated snippets)
- Document 401 once in every spec's auth scheme description
- Correct wrong facts: workflow run detail returns inputs as a JSON
  string; DELETE /conversations requires a JSON body; audio-to-text
  accepts audio/{mp3,m4a,wav,amr,mpga} by MIME type; workflow log
  created_by_account filters by email; triggered_from values are
  app-run/webhook/schedule/plugin; stop endpoints' user semantics
  differ per app type
- Remove unreachable docs: phantom text_replace SSE event, annotation
  403, file preview endpoint in the workflow spec, invented
  score_threshold bounds
- Make upload user optional (DEFAULT-USER fallback), fix upload
  response example, add missing invalid_param error
- Declare text_to_speech.autoPlay in parameters responses (prose
  values, no response-field enums)

* fix: complete API reference audit for knowledge and completion specs

* feat: add API spec consolidation pipeline

Phase-1 of the API docs consolidation: tooling that merges the five per-app-type Service API specs into one openapi_service.json per language, with every divergence resolved explicitly in resolutions.json and rendering-preserving namespacing for mode-scoped schema families. Includes the audit lint and parity checks (lint taught the new language-prefixed href scheme), hand-merged mode-aware SSE documentation for POST /chat-messages in en/zh/ja, and the New Agent (Beta) virtual nav group with code-verified mode notes.

* feat: consolidate API reference into one spec per language

Emit {en,zh,ja}/api-reference/openapi_service.json (82 ops, 130 components) from the audit-fixed per-app-type specs; wire docs.json to them with explicit per-app-type endpoint lists, x-mint.href URLs (/{lang}/api-reference/{tag}/{summary} with shared English slugs for in-place language switching), 265 redirects covering the legacy en and CJK URLs, per-app-type overview pages including New Agent (Beta), and rewritten legacy API links in 21 MDX bodies. The old five specs per language stay as pipeline input; they are no longer rendered.

* fix: remove dead conversation_completed error from chat specs

ConversationCompletedError is never raised anywhere at the verified 1.15.0 ref (7a4252b3de): controllers catch it, but no service code raises it, so the documented 400 conversation_completed can never fire. Remove the bullet and example from the chat and chatflow /chat-messages docs in en/zh/ja. Found and adversarially confirmed during the New Agent (PR #836) verification; filed on the upstream bug list.

* feat: add membership matrix and restructure nav config

* feat: rename resource tags and update all references

* feat: stamp per-operation availability lines

* feat: wire three-group API navigation

* feat: add app-type page coverage lint

* docs: rewrite chatflow overview as app-type API guide

* docs: polish chatflow overview zh and ja wording

* docs: rewrite workflow overview as app-type API guide

* docs: align workflow overview details across languages

* docs: expand new agent overview into app-type API guide

* docs: use task-oriented heading on new agent overview

* docs: rewrite chatbot and agent overview as app-type API guide

* docs: rewrite text generator overview as app-type API guide

* docs: match end user link text to merged spec summary

* docs: rewrite knowledge overview as app-type API guide

* docs: move knowledge api guide into api reference

* docs: localize ui labels on knowledge overview

* docs: refresh pipeline readme for restructure modes

* docs: name app-type pages in the guides sidebar

* feat: rename zh completion messages tag to match resource framing

* docs: prototype endpoints-first layout on chatflow overview

* docs: correct detail accuracy on chatflow overview

* docs: move human input flow guide into api reference

Move the shared HITL API integration walkthrough from its six per-product
copies into {en,zh,ja}/api-reference/guides/human-input-flow as the first
task guide in the API docs. Guides gains an App Types subgroup (expanded
by default) with the flow guide after it; six redirects cover the old
paths; the Human Input node docs and the chatflow overview link to the
new home.

* fix: update spec links to the moved human input guide

* fix: let spec lint accept mdx guide pages under api-reference

* docs: align chatflow zh and ja overviews to endpoints-first layout

* docs: polish chatflow zh and ja mode terms and hitl wording

* docs: align workflow overviews to endpoints-first layout

* docs: document form expiry path in human input flow guide

* docs: align new agent overviews to endpoints-first layout

* docs: align chatbot and agent overviews to endpoints-first layout

* docs: align text generator overviews to endpoints-first layout

* docs: align knowledge overviews to endpoints-first layout

* docs: correct built-in metadata examples and agent heading

* docs: flatten app-type pages directly under guides

* docs: make guide pages self-contained and trim reference detail

* docs: add get started guide and retire developing-with-apis

* docs: update new agent api behavior for latest main

New Agent behavior re-verified against dify origin/main (f3ba2846):
agent_thought events now stream through the Service API carrying the
model's reasoning steps and tool calls; a new agent_not_published 400
fires on Send Chat Message and Get App Parameters; the files claim is
softened to contents-not-processed (raw references now reach the prompt;
runtime confirmation pending). Streaming-only, message_end metadata, and
the endpoint surface are unchanged.

* docs: audit fixes for get started and human input flow guides

* docs: fix em dash spacing and ja sentence length in get started

* docs: move message_end note to the send endpoint line

* docs: update writing guides and API skill for app-type naming

- Glossary and zh/ja translation guides: Workflow and Chatflow app types stay English (Workflow 应用 / Chatflow アプリ); lowercase workflow localizes to 工作流 / ワークフロー.
- formatting-guide: API reference links use the language prefix with English slugs.
- dify-docs-api-reference skill: Spec Structure documents source specs merged into openapi_service.json by the pipeline.

* feat: add operation sidebar titles and simplify API redirects

- merge_specs stamps x-mint.metadata.sidebarTitle per operation so translated summaries show in the sidebar.
- Redirects reduced to a catch-all to the English API home plus three knowledge-base exceptions.
- memberships, strings, and SSE overrides carry app-type labels (Workflow/Chatflow English, New Agent, API Overviews group).

* docs: correct app-type naming and translations across API specs

- English mode enum labels Chatflow and Workflow apps.
- zh/ja app references use Workflow/Chatflow; New Agent is 新 Agent / 新しい Agent.
- ja knowledge tag データセット becomes ナレッジベース; zh 模型提供商 becomes 模型供应商.
- Regenerate merged openapi_service.json with per-operation sidebar titles.

* docs: add streaming, errors, and end-user identity API guides

- Consume Streaming Responses: response modes, SSE parsing, event dispatch, and reconnect.
- Handle Errors and Rate Limits: the error envelope, status classes, and retry guidance.
- End User Identity: what the user field scopes and why it stays consistent.
- English source with zh and ja translations.

* docs: reconcile API guides and apply app-type naming

- Reader-test fixes and content audit on get-started and the app-type overview pages.
- zh/ja reconciled to the English source.
- Workflow/Chatflow and New Agent naming applied in prose.

* feat: wire API nav and redirects for consolidated guides

- Rename the guides group to API Overviews and register the new guide pages.
- Redirects: catch-all to the English API home plus three product-embedded knowledge-base links to the Knowledge guide.

* fix: normalize zh model-provider term to 模型供应商

Aligns the POSITION_PROVIDER_* descriptions with the canonical glossary term.

* docs: use Info callouts for guide forward-link notes

Wrap the authentication, base URL, and `user` field forward-reference in each app-type guide (agent, chat, chatflow, completion, workflow; en/zh/ja) in an `<Info>` callout.

* refactor: remove one-time analyze mode and verification compose

- Drop the `analyze` mode (design-time spec-overlap analysis) and its helpers; the merge is stable and nothing invokes it.
- Delete `compose.swagger.yml`, the throwaway local code-vs-spec verification stack (flagged in review for inline credentials).
- README: drop the analyze entry and correct the redirect description.

* fix: correct Chatflow naming and reasoning wording in SSE overrides

- Use "Chatflow" (English) for the app type in the `/chat-messages` SSE tables instead of 对话流/チャットフロー, and fix the legacy zh chatflow "对话流工作流" description. Standalone table cells were missed by the earlier app-type rename.
- Describe `reasoning_chunk` as "reasoning content" in en/ja (matching the `reasoning` field and the zh wording) instead of "chain-of-thought".

* docs: refine API guide wording and simplify the human-input example

* docs: standardize Workflow and Chatflow app-type capitalization

Capitalize Chatflow and Workflow when they name an app type; keep "workflow" lowercase for the general engine, graph, or run sense.

* fix: use 供应商 for model provider in the zh Knowledge spec

* fix: rename the Knowledge API nav group to "Knowledge APIs"

* fix: un-deprecate Update Document by Text in the Knowledge spec

* translate: un-deprecate Update Document by Text in zh/ja specs

Mirror the en fix (6802d5eb) into the zh and ja Knowledge specs, source and merged: drop the deprecated flag and the leading Deprecated notice from the update-by-text operation. It is the canonical text-update route; only Update Document by File stays deprecated.
2026-07-09 16:40:54 +08:00

4422 lines
174 KiB
JSON
Raw Blame History

{
"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": "https://{api_base_url}",
"description": "Base URL of the Workflow App API. For self-hosted deployments, replace it with your own API base URL.",
"variables": {
"api_base_url": {
"default": "api.dify.ai/v1",
"description": "Host and path of the API base URL, without the `https://` prefix."
}
}
}
],
"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**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries no `message_id` or `conversation_id`. The parallel `text_chunk` stream stays free of `<think>` tags.\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\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} 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\": \"paragraph\", \"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**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries no `message_id` or `conversation_id`. The parallel `text_chunk` stream stays free of `<think>` tags.\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\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} 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\": \"paragraph\", \"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": "List past workflow runs with optional filters. Each entry is a run-level summary (status, token usage, step count, and timing), not a node-by-node execution log.\n\nTo follow a run's node-level events, stream it instead:\n\n- **A run you start**: use [Run Workflow](/api-reference/workflows/run-workflow) in streaming mode, which emits `node_started` and `node_finished` as the run executes.\n- **A run already in progress**: call [Stream Workflow Events](/api-reference/workflows/stream-workflow-events) with `include_state_snapshot=true` to replay each executed node's status, then stream the rest.\n\nA finished run's node-level logs aren't available through the Service API.",
"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 the creator's account email (e.g., `name@example.com`).",
"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-run"
},
"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, used to attribute the stop request to an end user. It does not need to match the `user` passed to [Run Workflow](/api-reference/workflows/run-workflow); the stop applies to the task regardless of user."
}
}
},
"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": "Identifier for the end user, defined by your application's rules and unique within the app. Service API and WebApp user IDs are separate, even when identical. If omitted, the upload is attributed to the shared `DEFAULT-USER` end user; a file can only be used later by requests carrying the same `user` value."
}
}
}
}
}
},
"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": "https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI=",
"original_url": null,
"user_id": null,
"tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
"conversation_id": null,
"file_key": null
}
}
}
}
}
},
"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.\n- `invalid_param` : The filename contains invalid characters (`/` or `\\`).",
"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."
}
},
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Filename contains invalid characters"
}
}
}
}
}
},
"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."
}
}
}
}
}
}
}
}
},
"/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. The uploaded file's MIME type must be one of `audio/mp3`, `audio/m4a`, `audio/wav`, `audio/amr`, `audio/mpga`; other types, including the common `audio/mpeg`, are rejected with the `unsupported_audio_type` error. 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. Requires WebApp delivery.\n\nSee the [API Integration Flow](/en/api-reference/guides/human-input-flow) for the end-to-end sequence of calling Human Input endpoints.",
"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 the Run Workflow or Send Chat Message endpoint 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: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads)."
},
"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": "Raw default-value configuration for `paragraph` inputs. The client should not resolve this directly; use `resolved_default_values` to display defaults. `null` for other input types or 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."
}
}
},
"option_source": {
"type": "object",
"description": "Source of options for `select` inputs. Present only when `type` is `select`.",
"properties": {
"type": {
"type": "string",
"enum": [
"variable",
"constant"
],
"description": "Origin of the options. `constant` means `value` lists the options literally; `variable` means `selector` points to an `array[string]` workflow variable that provides them."
},
"selector": {
"type": "array",
"items": {
"type": "string"
},
"description": "Variable reference path when `type` is `variable`."
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"description": "Literal option list when `type` is `constant`."
}
}
},
"allowed_file_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"image",
"document",
"audio",
"video",
"custom"
]
},
"description": "File categories the recipient may upload. Present for `file` and `file-list` inputs. Values: `image`, `document`, `audio`, `video`, `custom`."
},
"allowed_file_extensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed file extensions when `allowed_file_types` includes `custom`. Include the leading `.` in each extension, for example `.md`. Present for `file` and `file-list` inputs."
},
"allowed_file_upload_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"local_file",
"remote_url"
]
},
"description": "Upload methods the recipient may use. Values: `local_file`, `remote_url`. Present for `file` and `file-list` inputs."
},
"number_limits": {
"type": "integer",
"description": "Maximum number of files the recipient may upload. Present only for `file-list` inputs."
}
}
},
"description": "Form input field definitions."
},
"resolved_default_values": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Pre-rendered values to display in the form. Keyed by input `output_variable_name`. Populated for `paragraph` inputs whose default resolves from a workflow variable; empty for inputs with no resolvable default. Display these values; do not re-resolve `default` on the client. 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.",
"nullable": true
}
}
},
"examples": {
"success": {
"summary": "Response Example",
"value": {
"form_content": "Please review the draft, set a priority, and confirm or request changes.",
"inputs": [
{
"type": "paragraph",
"output_variable_name": "feedback",
"default": {
"type": "constant",
"selector": [],
"value": ""
}
},
{
"type": "select",
"output_variable_name": "priority",
"option_source": {
"type": "constant",
"selector": [],
"value": [
"low",
"medium",
"high"
]
}
},
{
"type": "file",
"output_variable_name": "attachment",
"allowed_file_types": [
"image",
"document"
],
"allowed_file_extensions": [],
"allowed_file_upload_methods": [
"local_file",
"remote_url"
]
},
{
"type": "file-list",
"output_variable_name": "attachments",
"allowed_file_types": [
"image",
"document"
],
"allowed_file_extensions": [],
"allowed_file_upload_methods": [
"local_file",
"remote_url"
],
"number_limits": 5
}
],
"resolved_default_values": {
"feedback": ""
},
"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; follow subsequent events via the Stream Workflow Events endpoint. 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 the Run Workflow or Send Chat Message endpoint in streaming mode."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"inputs",
"action",
"user"
],
"properties": {
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "Submitted values keyed by each input's `output_variable_name`. Paragraph and select inputs take a string; a `file` input takes one file mapping; a `file-list` input takes an array of file mappings. A file mapping is `{transfer_method: local_file, upload_file_id, type}` or `{transfer_method: remote_url, url, type}`, where `type` is one of the field's `allowed_file_types` (`image`, `document`, `audio`, `video`, `custom`). For `local_file`, `upload_file_id` is the `id` from [Upload File](/api-reference/files/upload-file). Use a consistent `user` across the run, upload, and submit."
},
"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))."
},
"user": {
"type": "string",
"description": "Identifier for the end user, defined by your application's rules and unique within the app. Service API and WebApp user IDs are separate, even when identical."
}
}
},
"examples": {
"approve": {
"summary": "Request Example",
"value": {
"inputs": {
"feedback": "Looks good to ship",
"priority": "high",
"attachment": {
"transfer_method": "local_file",
"upload_file_id": "3c8fa1b2-7d4e-4f9a-b0c1-d2e3f4a5b6c7",
"type": "image"
},
"attachments": [
{
"transfer_method": "local_file",
"upload_file_id": "1a77f0df-c0e6-461c-987c-e72526f341ee",
"type": "document"
},
{
"transfer_method": "remote_url",
"url": "https://example.com/report.pdf",
"type": "document"
}
]
},
"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: feedback"
}
}
}
}
}
},
"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/{workflow_run_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.\n\nTo check an in-progress run's node-level status and progress, call it with `include_state_snapshot=true`: the stream replays each already-executed node's status before streaming new events.",
"operationId": "streamWorkflowEvents",
"parameters": [
{
"name": "workflow_run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "The workflow run ID (the `workflow_run_id` from the original run response) whose event stream to resume."
},
{
"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 events from a resumed workflow run, in the same format as [Run Workflow](/api-reference/workflows/run-workflow). When the resumed portion runs an LLM node with `reasoning_format: separated`, this stream also carries `reasoning_chunk` events."
},
"examples": {
"resumedRun": {
"summary": "Response Example - Resumed run",
"value": "data: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_2\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Approved, now translating.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} 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\"}, \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}"
}
}
}
}
},
"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"
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "Resume stream",
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
},
{
"lang": "bash",
"label": "With state snapshot",
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}&include_state_snapshot=true' \\\n --header 'Authorization: Bearer {api_key}'"
}
]
}
}
},
"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.** Requests with a missing or invalid API key fail with HTTP `401` and error code `unauthorized`."
}
},
"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",
"reasoning_chunk",
"text_chunk",
"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",
"reasoning_chunk": "#/components/schemas/StreamEventReasoningChunk",
"text_chunk": "#/components/schemas/StreamEventTextChunk",
"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."
}
}
}
}
}
]
},
"StreamEventReasoningChunk": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkWorkflowEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"reasoning": {
"type": "string",
"description": "Chain-of-thought delta emitted by an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning. This stream is parallel to `text_chunk`; the `text` stream stays free of `<think>` tags."
},
"node_id": {
"type": "string",
"nullable": true,
"description": "ID of the LLM node producing the reasoning. Lets you attribute reasoning when multiple LLM nodes run."
},
"is_final": {
"type": "boolean",
"description": "`true` marks the end of an LLM node's reasoning phase (the \"thinking finished\" signal); it may arrive with an empty `reasoning`."
}
}
}
}
}
]
},
"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."
}
}
}
}
}
]
},
"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": "string",
"nullable": true,
"description": "Input variables of the workflow run, returned as a raw JSON string that clients must parse (e.g., `{\"query\": \"...\"}`). May be `null`."
},
"outputs": {
"type": "object",
"additionalProperties": true,
"description": "Output data from the workflow. An empty object until outputs are available."
},
"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",
"description": "Signed URL for downloading the file."
},
"original_url": {
"type": "string",
"nullable": true,
"description": "Original URL of the file."
},
"user_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Unused; always `null`."
},
"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": "Unused; always `null`."
}
}
},
"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. `app-run` for runs started from the app or API, `webhook` for runs started by a webhook trigger, `schedule` for runs started by a schedule trigger, `plugin` for runs started by a plugin trigger."
}
}
},
"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. Validated by MIME type: `audio/mp3`, `audio/m4a`, `audio/wav`, `audio/amr`, or `audio/mpga`. 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."
},
"autoPlay": {
"type": "string",
"description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play."
}
}
},
"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: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads)."
},
"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 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."
}
]
}
Reference in New Issue View Git Blame Copy Permalink