langgenius/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-07-23 12:55:46 -04:00
Code Issues 10 Packages Projects Releases Wiki Activity
Files
6258bbfb0f653f3caaa06fae84207c82041b0ac8
dify-docs/en/api-reference/openapi_chatflow.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

6831 lines
253 KiB
JSON
Raw Blame History

{
"openapi": "3.0.1",
"info": {
"title": "Chatflow App API",
"description": "Chatflow applications support session persistence, allowing previous chat history to be used as context for responses. Chatflow apps use the `advanced-chat` mode, providing workflow-level streaming events for detailed execution tracking including node starts, finishes, iterations, and workflow lifecycle.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://{api_base_url}",
"description": "Base URL of the Chatflow 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": {
"/chat-messages": {
"post": {
"summary": "Send Chat Message",
"description": "Send a request to the chat application.",
"operationId": "sendAdvancedChatMessage",
"tags": [
"Chatflows"
],
"requestBody": {
"description": "Request body to send a chat message.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatRequest"
},
"examples": {
"streaming_example": {
"summary": "Request Example - Streaming mode",
"value": {
"inputs": {
"city": "San Francisco"
},
"query": "What are the specs of the iPhone 13 Pro Max?",
"response_mode": "streaming",
"conversation_id": "",
"user": "abc-123",
"files": [
{
"type": "image",
"transfer_method": "remote_url",
"url": "https://cloud.dify.ai/logo/logo-site.png"
}
]
}
},
"blocking_example": {
"summary": "Request Example - Blocking mode",
"value": {
"inputs": {},
"query": "What are the specs of the iPhone 13 Pro Max?",
"response_mode": "blocking",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of Server-Sent Events.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionResponse"
},
"examples": {
"blockingResponse": {
"summary": "Response Example - Blocking mode",
"value": {
"event": "message",
"task_id": "c3800678-a077-43df-a102-53f23ed20b88",
"id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"mode": "advanced-chat",
"answer": "iPhone 13 Pro Max specs are listed here:...",
"metadata": {
"usage": {
"prompt_tokens": 1033,
"prompt_unit_price": "0.001",
"prompt_price_unit": "0.001",
"prompt_price": "0.0010330",
"completion_tokens": 128,
"completion_unit_price": "0.002",
"completion_price_unit": "0.001",
"completion_price": "0.0002560",
"total_tokens": 1161,
"total_price": "0.0012890",
"currency": "USD",
"latency": 0.7682376249867957
},
"retriever_resources": [
{
"position": 1,
"dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
"dataset_name": "iPhone",
"document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00",
"document_name": "iPhone List",
"segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a",
"score": 0.98457545,
"content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""
}
]
},
"created_at": 1705407629
}
}
}
},
"text/event-stream": {
"schema": {
"type": "string",
"description": "A stream of Server-Sent Events (SSE).\n\n**Parsing**: Each event is a line prefixed 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 arrive as `event: ping` lines (no `data:` payload) every 10 seconds to keep the connection alive.\n\n**Stream lifecycle**: Workflow progress streams as `workflow_started`, node events (`node_started` and `node_finished`, plus iteration and loop variants), and the reply as `message` events (an LLM node with `reasoning_format: separated` also emits `reasoning_chunk` events alongside, carrying the model's chain-of-thought). The closing sequence depends on the outcome:\n- **Success**: `message_end`, then `workflow_finished`\n- **Failure**: `workflow_finished` with status `failed`, then `error`; no `message_end`\n- **Pause**: `human_input_required`, then `workflow_paused` (the stream ends here; the run resumes separately)\n\nWhen text-to-speech auto-play is enabled, `tts_message_end` trails the closing event.\n\n**Events**: Apart from `ping`, every event includes `conversation_id`, `message_id`, and `created_at` (Unix epoch seconds); all but `error` also include `task_id`. Workflow, node, and human-input events also nest their payload under `data` and, except for `agent_log`, carry a top-level `workflow_run_id`.\n\n**Reply events**\n\n| Event | Fires on | Key fields |\n|:---|:---|:---|\n| `message` | each answer chunk (concatenate in order) | `answer` |\n| `message_replace` | output moderation replaces the answer so far | `answer`, `reason` |\n| `reasoning_chunk` | each chain-of-thought delta, when an LLM node uses `reasoning_format: separated` (concatenate in order; a final `is_final: true` event marks thinking finished and may carry an empty `reasoning`) | `data.message_id`, `data.reasoning`, `data.node_id`, `data.is_final` |\n| `message_end` | the answer is complete | `metadata` (`usage`, `retriever_resources`) |\n| `tts_message`, `tts_message_end` | audio chunk / end, when TTS auto-play is on | `audio` |\n\n**Workflow and node events**\n\nEach event nests its payload under a `data` object.\n\n| Event | Fires on | Key `data` fields |\n|:---|:---|:---|\n| `workflow_started` | the run begins | `inputs` |\n| `node_started` | a node begins | `node_id`, `node_type`, `title` |\n| `node_finished` | a node ends | `status`, `outputs`, `execution_metadata` |\n| `node_retry` | a node retries after a failure | `retry_index` |\n| `iteration_started`, `iteration_next`, `iteration_completed` | Iteration node progress (informational) | `data` |\n| `loop_started`, `loop_next`, `loop_completed` | Loop node progress (informational) | `data` |\n| `agent_log` | an Agent node step log (informational; no `workflow_run_id`) | `data` |\n| `workflow_finished` | the run ends | `status` (`succeeded`, `failed`, `partial-succeeded`, `stopped`), `outputs`, `total_tokens` |\n| `workflow_paused` | the run pauses | `paused_nodes`, `reasons` |\n| `human_input_required` | the run reaches a Human Input node | `form_token`, `form_content`, `expiration_time` |\n\nAfter a pause this stream ends at `workflow_paused`. Submit the form via [Submit Human Input Form](/api-reference/human-input/submit-human-input-form) or let it time out; the resumed run, including `human_input_form_filled`/`human_input_form_timeout` through `workflow_finished`, streams from [Stream Workflow Events](/api-reference/chatflows/stream-workflow-events).\n\n**Transport events**\n\n| Event | Fires on | Key fields |\n|:---|:---|:---|\n| `error` | a failure ends the stream; HTTP stays `200` | `status` (e.g. `400`), `code` (e.g. `invalid_param`), `message` |\n| `ping` | keep-alive every 10 seconds | none |"
},
"examples": {
"streamingResponseBasic": {
"summary": "Response Example - Streaming (Basic)",
"value": "data: {\"event\": \"message\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"created_at\": 1679586595, \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}"
},
"streamingResponseWorkflow": {
"summary": "Response Example - Streaming (Workflow)",
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"The user greeted me, so\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395335, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}"
},
"humanInputPause": {
"summary": "Response Example - Human Input pause",
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"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\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"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\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"paused_nodes\": [\"approval_node\"], \"outputs\": {}, \"reasons\": [{\"TYPE\": \"human_input_required\", \"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"resolved_default_values\": {\"comment\": \"\"}, \"form_token\": \"tok_abc123\", \"expiration_time\": 1705494029}], \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5, \"total_tokens\": 0, \"total_steps\": 1}}"
}
}
}
}
},
"400": {
"description": "- `app_unavailable` : App unavailable or misconfigured.\n- `not_chat_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` : Text generation failed.\n- `bad_request` : Cannot use draft workflow version.\n- `bad_request` : Invalid `workflow_id` format.",
"content": {
"application/json": {
"examples": {
"app_unavailable": {
"summary": "app_unavailable",
"value": {
"status": 400,
"code": "app_unavailable",
"message": "App unavailable, please check your app configurations."
}
},
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"provider_quota_exceeded": {
"summary": "provider_quota_exceeded",
"value": {
"status": 400,
"code": "provider_quota_exceeded",
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
}
},
"model_currently_not_support": {
"summary": "model_currently_not_support",
"value": {
"status": 400,
"code": "model_currently_not_support",
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
}
},
"completion_request_error": {
"summary": "completion_request_error",
"value": {
"status": 400,
"code": "completion_request_error",
"message": "Completion request failed."
}
},
"is_draft_workflow": {
"summary": "bad_request",
"value": {
"status": 400,
"code": "bad_request",
"message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. "
}
},
"workflow_id_format_error": {
"summary": "bad_request",
"value": {
"status": 400,
"code": "bad_request",
"message": "Invalid workflow_id format: 'not-a-valid-id'. "
}
}
}
}
}
},
"404": {
"description": "- `not_found` : Conversation does not exist.\n- `not_found` : Workflow not found with the specified `workflow_id`.",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
},
"workflow_not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}
}
}
}
},
"429": {
"description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.",
"content": {
"application/json": {
"examples": {
"too_many_requests": {
"summary": "too_many_requests",
"value": {
"status": 429,
"code": "too_many_requests",
"message": "Too many requests. Please try again later."
}
},
"rate_limit_error": {
"summary": "rate_limit_error",
"value": {
"status": 429,
"code": "rate_limit_error",
"message": "Rate Limit Error"
}
}
}
}
}
},
"500": {
"description": "`internal_server_error` : Internal server error.",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "internal_server_error",
"value": {
"status": 500,
"code": "internal_server_error",
"message": "Internal server error."
}
}
}
}
}
}
}
}
},
"/chat-messages/{task_id}/stop": {
"post": {
"summary": "Stop Chat Message Generation",
"description": "Stops a chat message generation task. Only supported in `streaming` mode.",
"operationId": "stopAdvancedChatMessageGeneration",
"tags": [
"Chatflows"
],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"description": "Task ID, can be obtained from the streaming chunk return of the [Send Chat Message](/api-reference/chatflows/send-chat-message) API.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"user"
],
"properties": {
"user": {
"type": "string",
"description": "User identifier. Must match the `user` passed when the message was sent: if it differs, the stop silently does nothing and the response still returns success."
}
}
},
"examples": {
"example": {
"summary": "Request Example",
"value": {
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SuccessResult"
},
"400": {
"description": "`not_chat_app` : App mode does not match the API route.",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
}
}
}
},
"/messages/{message_id}/suggested": {
"get": {
"summary": "Get Next Suggested Questions",
"description": "Get next questions suggestions for the current message.",
"operationId": "getAdvancedSuggestedQuestions",
"tags": [
"Chatflows"
],
"parameters": [
{
"name": "message_id",
"in": "path",
"required": true,
"description": "Message ID.",
"schema": {
"type": "string"
}
},
{
"name": "user",
"in": "query",
"required": true,
"description": "User identifier.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved suggested questions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuggestedQuestionsResponse"
},
"examples": {
"suggestedQuestions": {
"summary": "Response Example",
"value": {
"result": "success",
"data": [
"What colors does the iPhone 13 Pro Max come in?",
"How does the battery compare to iPhone 12?",
"What is the price range?"
]
}
}
}
}
}
},
"400": {
"description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Suggested questions feature is disabled.",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
},
"bad_request": {
"summary": "bad_request",
"value": {
"status": 400,
"code": "bad_request",
"message": "Suggested Questions Is Disabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : Message does not exist.",
"content": {
"application/json": {
"examples": {
"message_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Message Not Exists."
}
}
}
}
}
},
"500": {
"description": "`internal_server_error` : Internal server error.",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "internal_server_error",
"value": {
"status": 500,
"code": "internal_server_error",
"message": "Internal server error."
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages/{message_id}/suggested?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
}
]
}
},
"/files/upload": {
"post": {
"operationId": "uploadAdvancedChatFile",
"tags": [
"Files"
],
"summary": "Upload File",
"description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.",
"requestBody": {
"description": "File upload request. Requires multipart/form-data.",
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The file to be uploaded. Supported types include images, documents, audio, and video."
},
"user": {
"type": "string",
"description": "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."
}
}
}
}
}
}
}
}
},
"/files/{file_id}/preview": {
"get": {
"operationId": "previewChatFlowFile",
"tags": [
"Files"
],
"summary": "Download File",
"description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.",
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "as_attachment",
"in": "query",
"required": false,
"description": "If `true`, forces the file to download as an attachment instead of previewing in browser.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "user",
"in": "query",
"required": false,
"description": "User identifier, used for end-user context.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"403": {
"description": "`file_access_denied` : Access to the requested file is denied.",
"content": {
"application/json": {
"examples": {
"file_access_denied": {
"summary": "file_access_denied",
"value": {
"status": 403,
"code": "file_access_denied",
"message": "Access to the requested file is denied."
}
}
}
}
}
},
"404": {
"description": "`file_not_found` : The requested file was not found.",
"content": {
"application/json": {
"examples": {
"file_not_found": {
"summary": "file_not_found",
"value": {
"status": 404,
"code": "file_not_found",
"message": "The requested file was not found."
}
}
}
}
}
}
}
}
},
"/end-users/{end_user_id}": {
"get": {
"operationId": "getEndUserChatflow",
"tags": [
"End Users"
],
"summary": "Get End User Info",
"description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).",
"parameters": [
{
"name": "end_user_id",
"in": "path",
"required": true,
"description": "End user ID.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "End user retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EndUserDetail"
},
"examples": {
"endUserDetail": {
"summary": "Response Example",
"value": {
"id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"type": "service_api",
"external_user_id": "abc-123",
"name": null,
"is_anonymous": false,
"session_id": "abc-123",
"created_at": "2024-01-16T12:00:29Z",
"updated_at": "2024-01-16T12:00:29Z"
}
}
}
}
}
},
"404": {
"description": "`end_user_not_found` : End user not found.",
"content": {
"application/json": {
"examples": {
"end_user_not_found": {
"summary": "end_user_not_found",
"value": {
"status": 404,
"code": "end_user_not_found",
"message": "End user not found."
}
}
}
}
}
}
}
}
},
"/messages/{message_id}/feedbacks": {
"post": {
"operationId": "postAdvancedChatMessageFeedback",
"tags": [
"Feedback"
],
"summary": "Submit Message Feedback",
"description": "Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.",
"parameters": [
{
"name": "message_id",
"in": "path",
"required": true,
"description": "Message ID.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageFeedbackRequest"
},
"examples": {
"likeFeedback": {
"summary": "Request Example",
"value": {
"rating": "like",
"user": "abc-123",
"content": "This answer was very helpful!"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SuccessResult"
},
"404": {
"description": "`not_found` : Message does not exist.",
"content": {
"application/json": {
"examples": {
"message_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Message Not Exists."
}
}
}
}
}
}
}
}
},
"/app/feedbacks": {
"get": {
"operationId": "getAdvancedChatAppFeedbacks",
"tags": [
"Feedback"
],
"summary": "List App Feedbacks",
"description": "Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.",
"parameters": [
{
"name": "page",
"in": "query",
"description": "Page number for pagination.",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "limit",
"in": "query",
"description": "Number of records per page.",
"required": false,
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 101
}
}
],
"responses": {
"200": {
"description": "A list of application feedbacks.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppFeedbacksResponse"
},
"examples": {
"feedbacksList": {
"summary": "Response Example",
"value": {
"data": [
{
"id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456",
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"rating": "like",
"content": "The response accurately answered my question about product specifications.",
"from_source": "user",
"from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"from_account_id": null,
"created_at": "2025-01-16T14:30:29Z",
"updated_at": "2025-01-16T14:30:29Z"
},
{
"id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678",
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603",
"message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1",
"rating": "dislike",
"content": "The answer was too vague and did not address the specific pricing question.",
"from_source": "user",
"from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210",
"from_account_id": null,
"created_at": "2025-01-15T09:12:45Z",
"updated_at": "2025-01-15T09:12:45Z"
}
]
}
}
}
}
}
}
}
}
},
"/conversations": {
"get": {
"summary": "List Conversations",
"description": "Retrieve the conversation list for the current user, ordered by most recently active.",
"operationId": "getAdvancedConversationsList",
"tags": [
"Conversations"
],
"parameters": [
{
"name": "user",
"in": "query",
"required": false,
"description": "User identifier.",
"schema": {
"type": "string"
}
},
{
"name": "last_id",
"in": "query",
"required": false,
"description": "The ID of the last record on the current page (for pagination).",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Number of records to return.",
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 100
}
},
{
"name": "sort_by",
"in": "query",
"required": false,
"description": "Sorting field. Use '-' prefix for descending order.",
"schema": {
"type": "string",
"enum": [
"created_at",
"-created_at",
"updated_at",
"-updated_at"
],
"default": "-updated_at"
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved conversations list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationsListResponse"
},
"examples": {
"conversationsList": {
"summary": "Response Example",
"value": {
"limit": 20,
"has_more": false,
"data": [
{
"id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"name": "iPhone Specs Chat",
"inputs": {
"city": "San Francisco"
},
"status": "normal",
"introduction": "Welcome! How can I help you today?",
"created_at": 1705407629,
"updated_at": 1705411229
}
]
}
}
}
}
}
},
"400": {
"description": "`not_chat_app` : App mode does not match the API route.",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : Last conversation does not exist (invalid `last_id`).",
"content": {
"application/json": {
"examples": {
"last_conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Last Conversation Not Exists."
}
}
}
}
}
}
}
}
},
"/messages": {
"get": {
"summary": "List Conversation Messages",
"description": "Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order.",
"operationId": "getAdvancedConversationHistory",
"tags": [
"Conversations"
],
"parameters": [
{
"name": "conversation_id",
"in": "query",
"required": true,
"description": "Conversation ID.",
"schema": {
"type": "string"
}
},
{
"name": "user",
"in": "query",
"required": false,
"description": "User identifier.",
"schema": {
"type": "string"
}
},
{
"name": "first_id",
"in": "query",
"required": false,
"description": "The ID of the first chat record on the current page. Default is `null` (fetches the latest messages). For subsequent pages, use the ID of the first message from the current list to get older messages.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Number of chat history messages to return per request.",
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 100
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved conversation history.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationHistoryResponse"
},
"examples": {
"conversationHistory": {
"summary": "Response Example",
"value": {
"limit": 20,
"has_more": false,
"data": [
{
"id": "9da23599-e713-473b-982c-4328d4f5c78a",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"parent_message_id": null,
"inputs": {
"city": "San Francisco"
},
"query": "What are the specs of the iPhone 13 Pro Max?",
"answer": "iPhone 13 Pro Max specs are listed here:...",
"status": "normal",
"error": null,
"message_files": [],
"feedback": {
"rating": "like"
},
"retriever_resources": [],
"agent_thoughts": [],
"created_at": 1705407629
}
]
}
}
}
}
}
},
"400": {
"description": "`not_chat_app` : App mode does not match the API route.",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : Conversation does not exist.\n- `not_found` : First message does not exist.",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
},
"first_message_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "First Message Not Exists."
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages?conversation_id={conversation_id}&user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
}
]
}
},
"/conversations/{conversation_id}/variables": {
"get": {
"summary": "List Conversation Variables",
"description": "Retrieve variables from a specific conversation.",
"operationId": "getAdvancedConversationVariables",
"tags": [
"Conversations"
],
"parameters": [
{
"name": "conversation_id",
"in": "path",
"required": true,
"description": "Conversation ID.",
"schema": {
"type": "string"
}
},
{
"name": "user",
"in": "query",
"required": false,
"description": "The user identifier.",
"schema": {
"type": "string"
}
},
{
"name": "last_id",
"in": "query",
"required": false,
"description": "The ID of the last record on the current page (for pagination).",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Number of records to return.",
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 100
}
},
{
"name": "variable_name",
"in": "query",
"required": false,
"description": "Filter variables by a specific name.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved conversation variables.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationVariablesResponse"
},
"examples": {
"conversationVariables": {
"summary": "Response Example",
"value": {
"limit": 20,
"has_more": false,
"data": [
{
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"name": "user_preference",
"value_type": "string",
"value": "dark_mode",
"description": "User preference setting",
"created_at": 1705407629,
"updated_at": 1705411229
}
]
}
}
}
}
}
},
"400": {
"description": "`not_chat_app` : App mode does not match the API route.",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : Conversation does not exist.",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
}
}
}
}
}
}
}
},
"/conversations/{conversation_id}/name": {
"post": {
"summary": "Rename Conversation",
"description": "Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations.",
"operationId": "renameAdvancedConversation",
"tags": [
"Conversations"
],
"parameters": [
{
"name": "conversation_id",
"in": "path",
"required": true,
"description": "Conversation ID.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationRenameRequest"
},
"examples": {
"renameExample": {
"summary": "Request Example",
"value": {
"name": "iPhone Specs Chat",
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Conversation renamed successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationListItem"
},
"examples": {
"renamedConversation": {
"summary": "Response Example",
"value": {
"id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"name": "iPhone Specs Chat",
"inputs": {
"city": "San Francisco"
},
"status": "normal",
"introduction": "Welcome! How can I help you today?",
"created_at": 1705407629,
"updated_at": 1705411229
}
}
}
}
}
},
"400": {
"description": "`not_chat_app` : App mode does not match the API route.",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : Conversation does not exist.",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
}
}
}
}
}
}
}
},
"/conversations/{conversation_id}/variables/{variable_id}": {
"put": {
"summary": "Update Conversation Variable",
"description": "Update the value of a specific conversation variable. The value must match the expected type.",
"operationId": "updateChatflowConversationVariable",
"tags": [
"Conversations"
],
"parameters": [
{
"name": "conversation_id",
"in": "path",
"required": true,
"description": "Conversation ID.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "variable_id",
"in": "path",
"required": true,
"description": "Variable ID.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationVariableUpdateRequest"
},
"examples": {
"updateStringVariable": {
"summary": "Request Example",
"value": {
"value": "new value",
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Variable updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationVariableItem"
},
"examples": {
"updatedVariable": {
"summary": "Response Example",
"value": {
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"name": "user_preference",
"value_type": "string",
"value": "new value",
"description": "User preference setting",
"created_at": 1705407629,
"updated_at": 1705411229
}
}
}
}
}
},
"400": {
"description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Variable value type mismatch.",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
},
"type_mismatch": {
"summary": "bad_request",
"value": {
"status": 400,
"code": "bad_request",
"message": "Value type mismatch: expected string, got integer."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : Conversation does not exist.\n- `not_found` : Conversation variable does not exist.",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
},
"variable_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Variable Not Exists."
}
}
}
}
}
}
}
}
},
"/conversations/{conversation_id}": {
"delete": {
"summary": "Delete Conversation",
"description": "Delete a conversation.",
"operationId": "deleteAdvancedConversation",
"tags": [
"Conversations"
],
"parameters": [
{
"name": "conversation_id",
"in": "path",
"required": true,
"description": "Conversation ID.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "A JSON body is always required, even when `user` is omitted; send `{}` in that case.",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user": {
"type": "string",
"description": "The user identifier."
}
}
},
"examples": {
"deleteExample": {
"value": {
"user": "abc-123"
},
"summary": "Request Example"
}
}
}
}
},
"responses": {
"204": {
"description": "Conversation deleted successfully. No content returned."
},
"400": {
"description": "`not_chat_app` : App mode does not match the API route.",
"content": {
"application/json": {
"examples": {
"not_chat_app": {
"summary": "not_chat_app",
"value": {
"status": 400,
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : Conversation does not exist.",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
}
}
}
}
}
}
}
},
"/audio-to-text": {
"post": {
"operationId": "advancedAudioToText",
"tags": [
"TTS"
],
"summary": "Convert Audio to Text",
"description": "Convert audio file to text. 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": "advancedTextToAudio",
"tags": [
"TTS"
],
"summary": "Convert Text to Audio",
"description": "Convert text to speech.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TextToAudioRequest"
},
"examples": {
"textToAudioExample": {
"summary": "Request Example",
"value": {
"text": "Hello, welcome to our service.",
"user": "abc-123",
"voice": "alloy",
"streaming": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.",
"content": {
"audio/mpeg": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.",
"content": {
"application/json": {
"examples": {
"app_unavailable": {
"summary": "app_unavailable",
"value": {
"status": 400,
"code": "app_unavailable",
"message": "App unavailable, please check your app configurations."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"provider_quota_exceeded": {
"summary": "provider_quota_exceeded",
"value": {
"status": 400,
"code": "provider_quota_exceeded",
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
}
},
"model_currently_not_support": {
"summary": "model_currently_not_support",
"value": {
"status": 400,
"code": "model_currently_not_support",
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
}
},
"completion_request_error": {
"summary": "completion_request_error",
"value": {
"status": 400,
"code": "completion_request_error",
"message": "Completion request failed."
}
}
}
}
}
},
"500": {
"description": "`internal_server_error` : Internal server error.",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "internal_server_error",
"value": {
"status": 500,
"code": "internal_server_error",
"message": "Internal server error."
}
}
}
}
}
}
}
}
},
"/info": {
"get": {
"operationId": "getAdvancedChatAppInfo",
"tags": [
"Applications"
],
"summary": "Get App Info",
"description": "Retrieve basic information about this application, including name, description, tags, and mode.",
"responses": {
"200": {
"description": "Basic information of the application.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppInfoResponse"
},
"examples": {
"appInfo": {
"summary": "Response Example",
"value": {
"name": "My Chatflow App",
"description": "A helpful customer service chatbot.",
"tags": [
"customer-service",
"chatbot"
],
"mode": "advanced-chat",
"author_name": "Dify Team"
}
}
}
}
}
}
}
}
},
"/parameters": {
"get": {
"operationId": "getAdvancedChatAppParameters",
"tags": [
"Applications"
],
"summary": "Get App Parameters",
"description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.",
"responses": {
"200": {
"description": "Application parameters information.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAppParametersResponse"
},
"examples": {
"appParameters": {
"summary": "Response Example",
"value": {
"opening_statement": "Hello! How can I help you today?",
"suggested_questions": [
"What can you do?",
"Tell me about your features."
],
"suggested_questions_after_answer": {
"enabled": true
},
"speech_to_text": {
"enabled": false
},
"text_to_speech": {
"enabled": false,
"voice": "alloy",
"language": "en-US",
"autoPlay": "disabled"
},
"retriever_resource": {
"enabled": true
},
"annotation_reply": {
"enabled": false
},
"more_like_this": {
"enabled": false
},
"sensitive_word_avoidance": {
"enabled": false
},
"user_input_form": [
{
"text-input": {
"label": "City",
"variable": "city",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": true,
"number_limits": 3,
"detail": "high",
"transfer_methods": [
"remote_url",
"local_file"
]
}
},
"system_parameters": {
"file_size_limit": 15,
"image_file_size_limit": 10,
"audio_file_size_limit": 50,
"video_file_size_limit": 100,
"workflow_file_upload_limit": 10
}
}
}
}
}
}
},
"400": {
"description": "`app_unavailable` : App unavailable or misconfigured.",
"content": {
"application/json": {
"examples": {
"app_unavailable": {
"summary": "app_unavailable",
"value": {
"status": 400,
"code": "app_unavailable",
"message": "App unavailable, please check your app configurations."
}
}
}
}
}
}
}
}
},
"/meta": {
"get": {
"operationId": "getAdvancedChatAppMeta",
"tags": [
"Applications"
],
"summary": "Get App Meta",
"description": "Retrieve metadata about this application, including tool icons and other configuration details.",
"responses": {
"200": {
"description": "Successfully retrieved application meta information.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppMetaResponse"
},
"examples": {
"appMeta": {
"summary": "Response Example",
"value": {
"tool_icons": {
"dalle3": "https://example.com/icons/dalle3.png",
"calculator": {
"background": "#4A90D9",
"content": "🧮"
}
}
}
}
}
}
}
}
}
}
},
"/site": {
"get": {
"operationId": "getAdvancedChatWebAppSettings",
"tags": [
"Applications"
],
"summary": "Get App WebApp Settings",
"description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.",
"responses": {
"200": {
"description": "WebApp settings of the application.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAppSettingsResponse"
},
"examples": {
"webAppSettings": {
"summary": "Response Example",
"value": {
"title": "My Chat App",
"chat_color_theme": "#4A90D9",
"chat_color_theme_inverted": false,
"icon_type": "emoji",
"icon": "🤖",
"icon_background": "#FFFFFF",
"icon_url": null,
"description": "A helpful customer service chatbot.",
"copyright": "2025 Dify",
"privacy_policy": "https://example.com/privacy",
"custom_disclaimer": "",
"default_language": "en-US",
"show_workflow_steps": false,
"use_icon_as_answer_icon": true
}
}
}
}
}
},
"403": {
"description": "`forbidden` : Site not found for this application or the workspace has been archived.",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden",
"value": {
"status": 403,
"code": "forbidden",
"message": "Forbidden."
}
}
}
}
}
}
}
}
},
"/apps/annotations": {
"post": {
"summary": "Create Annotation",
"description": "Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response.",
"operationId": "createAdvancedAnnotation",
"tags": [
"Annotations"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAnnotationRequest"
},
"examples": {
"createAnnotation": {
"summary": "Request Example",
"value": {
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform."
}
}
}
}
}
},
"responses": {
"201": {
"description": "Annotation created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnnotationItem"
},
"examples": {
"createdAnnotation": {
"summary": "Response Example",
"value": {
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform.",
"hit_count": 0,
"created_at": 1705407629
}
}
}
}
}
}
}
},
"get": {
"summary": "List Annotations",
"description": "Retrieves a paginated list of annotations for the application. Supports keyword search filtering.",
"operationId": "getAdvancedAnnotationList",
"tags": [
"Annotations"
],
"parameters": [
{
"name": "page",
"in": "query",
"description": "Page number for pagination.",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "limit",
"in": "query",
"description": "Number of items per page.",
"required": false,
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "keyword",
"in": "query",
"description": "Keyword to filter annotations by question or answer content.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved annotation list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnnotationListResponse"
},
"examples": {
"annotationList": {
"summary": "Response Example",
"value": {
"data": [
{
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform.",
"hit_count": 5,
"created_at": 1705407629
}
],
"has_more": false,
"limit": 20,
"total": 1,
"page": 1
}
}
}
}
}
}
}
}
},
"/apps/annotations/{annotation_id}": {
"put": {
"summary": "Update Annotation",
"description": "Updates the question and answer of an existing annotation.",
"operationId": "updateAdvancedAnnotation",
"tags": [
"Annotations"
],
"parameters": [
{
"name": "annotation_id",
"in": "path",
"required": true,
"description": "The unique identifier of the annotation to update.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAnnotationRequest"
},
"examples": {
"updateAnnotation": {
"summary": "Request Example",
"value": {
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform for building AI-powered apps."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Annotation updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnnotationItem"
},
"examples": {
"updatedAnnotation": {
"summary": "Response Example",
"value": {
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform for building AI-powered apps.",
"hit_count": 5,
"created_at": 1705407629
}
}
}
}
}
},
"404": {
"description": "`not_found` : Annotation does not exist.",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Annotation not found."
}
}
}
}
}
}
}
},
"delete": {
"summary": "Delete Annotation",
"description": "Deletes an annotation and its associated hit history.",
"operationId": "deleteAdvancedAnnotation",
"tags": [
"Annotations"
],
"parameters": [
{
"name": "annotation_id",
"in": "path",
"required": true,
"description": "The unique identifier of the annotation to delete.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Annotation deleted successfully."
},
"404": {
"description": "`not_found` : Annotation does not exist.",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Annotation not found."
}
}
}
}
}
}
}
}
},
"/apps/annotation-reply/{action}": {
"post": {
"summary": "Configure Annotation Reply",
"description": "Enables or disables the annotation reply feature. The request body is validated before the action runs, so `embedding_provider_name`, `embedding_model_name`, and `score_threshold` are required for both `enable` and `disable`. Executes asynchronously; use [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.",
"operationId": "initialAdvancedAnnotationReplySettings",
"tags": [
"Annotations"
],
"parameters": [
{
"name": "action",
"in": "path",
"required": true,
"description": "Action to perform.",
"schema": {
"type": "string",
"enum": [
"enable",
"disable"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest"
},
"examples": {
"enableAnnotationReply": {
"summary": "Request Example",
"value": {
"score_threshold": 0.9,
"embedding_provider_name": "openai",
"embedding_model_name": "text-embedding-3-small"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Annotation reply settings task initiated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse"
},
"examples": {
"annotationReplyResponse": {
"summary": "Response Example",
"value": {
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"job_status": "waiting"
}
}
}
}
}
}
}
}
},
"/apps/annotation-reply/{action}/status/{job_id}": {
"get": {
"summary": "Get Annotation Reply Job Status",
"description": "Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).",
"operationId": "getAdvancedInitialAnnotationReplySettingsStatus",
"tags": [
"Annotations"
],
"parameters": [
{
"name": "action",
"in": "path",
"required": true,
"description": "Action type, must match the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call.",
"schema": {
"type": "string",
"enum": [
"enable",
"disable"
]
}
},
{
"name": "job_id",
"in": "path",
"required": true,
"description": "Job ID returned by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved task status.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse"
},
"examples": {
"jobStatus": {
"summary": "Response Example",
"value": {
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"job_status": "completed",
"error_msg": ""
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : The specified job does not exist.",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "The job does not exist."
}
}
}
}
}
}
}
}
},
"/workflows/run/{workflow_run_id}": {
"get": {
"summary": "Get Workflow Run Detail",
"description": "Retrieve the current execution results of a workflow task based on the workflow execution ID.",
"operationId": "getChatflowWorkflowRunDetail",
"tags": [
"Chatflows"
],
"parameters": [
{
"name": "workflow_run_id",
"in": "path",
"required": true,
"description": "Workflow run ID, can be obtained from the streaming events or message metadata.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successfully retrieved workflow run details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowRunDetailResponse"
},
"examples": {
"workflowRunDetail": {
"summary": "Response Example",
"value": {
"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
"workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345",
"status": "succeeded",
"inputs": "{\"query\": \"Translate this to French\"}",
"outputs": {
"result": "Traduisez ceci en francais"
},
"error": null,
"total_steps": 3,
"total_tokens": 150,
"created_at": 1705407629,
"finished_at": 1705407630,
"elapsed_time": 1.23
}
}
}
}
}
},
"400": {
"description": "`not_workflow_app` : App mode does not match the API route.",
"content": {
"application/json": {
"examples": {
"not_workflow_app": {
"summary": "not_workflow_app",
"value": {
"status": 400,
"code": "not_workflow_app",
"message": "Please check if your app mode matches the right API route."
}
}
}
}
}
},
"404": {
"description": "`not_found` : Workflow run not found.",
"content": {
"application/json": {
"examples": {
"workflow_run_not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Workflow run not found."
}
}
}
}
}
}
}
}
},
"/workflows/logs": {
"get": {
"summary": "List Workflow Logs",
"description": "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 [Send Chat Message](/api-reference/chatflows/send-chat-message) 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/chatflows/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": "listChatflowWorkflowLogs",
"tags": [
"Chatflows"
],
"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
},
"created_from": "service-api",
"created_by_role": "end_user",
"created_by_account": null,
"created_by_end_user": {
"id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"type": "service_api",
"is_anonymous": false,
"session_id": "user_chatflow_123"
},
"created_at": 1705407629
}
]
}
}
}
}
}
}
}
}
},
"/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": "getChatflowHumanInputForm",
"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": "submitChatflowHumanInputForm",
"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": [
"Chatflows"
],
"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": "streamChatflowEvents",
"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 [Send Chat Message](/api-reference/chatflows/send-chat-message) response) whose event stream to resume."
},
{
"name": "user",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "End-user identifier that sent the chat message. 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 [Send Chat Message](/api-reference/chatflows/send-chat-message). 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\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"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\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"The reviewer approved the draft.\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"answer\": \"Approved\", \"created_at\": 1705407706} data: {\"event\": \"node_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"status\": \"succeeded\", \"elapsed_time\": 1.2, \"created_at\": 1705407705, \"finished_at\": 1705407706}} data: {\"event\": \"message_end\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"metadata\": {\"usage\": {\"total_tokens\": 42, \"latency\": 1.3}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"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",
"description": "Result status."
}
}
},
"examples": {
"success": {
"summary": "Response Example",
"value": {
"result": "success"
}
}
}
}
}
}
},
"schemas": {
"ChatRequest": {
"type": "object",
"required": [
"inputs",
"query",
"user"
],
"properties": {
"query": {
"type": "string",
"description": "User input/question content."
},
"inputs": {
"type": "object",
"description": "Allows the entry of various variable values defined by the App. Contains key/value pairs. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.",
"additionalProperties": true
},
"response_mode": {
"type": "string",
"enum": [
"streaming",
"blocking"
],
"description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior."
},
"user": {
"type": "string",
"description": "User identifier, unique within the application. This identifier scopes data access — conversations, messages, and files are only visible when queried with the same `user` value."
},
"conversation_id": {
"type": "string",
"description": "Conversation ID to continue a conversation. Pass the previous message's `conversation_id`. To start a new conversation, omit this field or pass an empty string. The response will return a `conversation_id` — pass it in subsequent messages to continue that conversation."
},
"files": {
"type": "array",
"description": "File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`.",
"items": {
"type": "object",
"required": [
"type",
"transfer_method"
],
"properties": {
"type": {
"type": "string",
"enum": [
"image",
"document",
"audio",
"video",
"custom"
],
"description": "File type."
},
"transfer_method": {
"type": "string",
"enum": [
"remote_url",
"local_file"
],
"description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file."
},
"url": {
"type": "string",
"format": "url",
"description": "File URL (required when `transfer_method` is `remote_url`)."
},
"upload_file_id": {
"type": "string",
"description": "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`)."
}
}
}
},
"auto_generate_name": {
"type": "boolean",
"description": "Auto-generate conversation title. If `false`, use the [Rename Conversation](/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation.",
"default": true
},
"workflow_id": {
"type": "string",
"description": "Specify a published workflow version ID to execute. If not provided, the latest published version is used."
}
}
},
"ChatCompletionResponse": {
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "Event type, fixed as `message`."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "Task ID for request tracking and stop response API."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Unique ID of this response event."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints."
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "Conversation ID."
},
"mode": {
"type": "string",
"description": "App mode, fixed as `advanced-chat`."
},
"answer": {
"type": "string",
"description": "Complete response content."
},
"metadata": {
"type": "object",
"description": "Metadata including usage and retriever resources.",
"properties": {
"usage": {
"$ref": "#/components/schemas/Usage"
},
"retriever_resources": {
"type": "array",
"description": "List of retriever resources used.",
"items": {
"$ref": "#/components/schemas/RetrieverResource"
}
}
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Message creation timestamp (Unix epoch seconds)."
}
}
},
"ChunkChatEvent": {
"type": "object",
"description": "Base schema for Server-Sent Event chunks in streaming mode.",
"properties": {
"event": {
"type": "string",
"description": "The type of event.",
"enum": [
"message",
"tts_message",
"tts_message_end",
"message_file",
"message_end",
"message_replace",
"reasoning_chunk",
"workflow_started",
"workflow_finished",
"node_started",
"node_finished",
"node_retry",
"iteration_started",
"iteration_next",
"iteration_completed",
"loop_started",
"loop_next",
"loop_completed",
"workflow_paused",
"human_input_required",
"human_input_form_filled",
"human_input_form_timeout",
"agent_log",
"text_chunk",
"error",
"ping"
]
}
},
"discriminator": {
"propertyName": "event",
"mapping": {
"message": "#/components/schemas/StreamEventChatMessage",
"tts_message": "#/components/schemas/StreamEventChatTtsMessage",
"tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd",
"message_file": "#/components/schemas/StreamEventChatMessageFile",
"message_end": "#/components/schemas/StreamEventChatMessageEnd",
"message_replace": "#/components/schemas/StreamEventChatMessageReplace",
"reasoning_chunk": "#/components/schemas/StreamEventChatReasoningChunk",
"workflow_started": "#/components/schemas/StreamEventWorkflowStarted",
"workflow_finished": "#/components/schemas/StreamEventWorkflowFinished",
"node_started": "#/components/schemas/StreamEventNodeStarted",
"node_finished": "#/components/schemas/StreamEventNodeFinished",
"node_retry": "#/components/schemas/StreamEventNodeRetry",
"iteration_started": "#/components/schemas/StreamEventIterationStarted",
"iteration_next": "#/components/schemas/StreamEventIterationNext",
"iteration_completed": "#/components/schemas/StreamEventIterationCompleted",
"loop_started": "#/components/schemas/StreamEventLoopStarted",
"loop_next": "#/components/schemas/StreamEventLoopNext",
"loop_completed": "#/components/schemas/StreamEventLoopCompleted",
"workflow_paused": "#/components/schemas/StreamEventWorkflowPaused",
"human_input_required": "#/components/schemas/StreamEventHumanInputRequired",
"human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled",
"human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout",
"agent_log": "#/components/schemas/StreamEventAgentLog",
"text_chunk": "#/components/schemas/StreamEventChatTextChunk",
"error": "#/components/schemas/StreamEventChatError",
"ping": "#/components/schemas/StreamEventChatPing"
}
}
},
"StreamEventBase": {
"type": "object",
"description": "Base properties for stream events.",
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "Task ID."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Unique message ID."
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "Conversation ID."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Creation timestamp."
}
}
},
"StreamEventChatMessage": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"answer": {
"type": "string",
"description": "LLM returned text chunk."
}
}
}
]
},
"StreamEventChatTtsMessage": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "TTS audio stream event (base64 encoded Mp3). Available if auto-play enabled.",
"properties": {
"audio": {
"type": "string",
"format": "byte",
"description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file."
}
}
}
]
},
"StreamEventChatTtsMessageEnd": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "TTS audio stream end event.",
"properties": {
"audio": {
"type": "string",
"description": "Empty string. Signals the end of the audio stream."
}
}
}
]
},
"StreamEventChatMessageFile": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Message file event, a new file created by a tool.",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "File unique ID."
},
"type": {
"type": "string",
"description": "File type, e.g. `image`."
},
"belongs_to": {
"type": "string",
"enum": [
"assistant"
],
"description": "Who this file belongs to, always `assistant` here."
},
"url": {
"type": "string",
"format": "url",
"description": "Remote URL of the file."
}
}
}
]
},
"StreamEventChatMessageEnd": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Message end event, streaming has ended.",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique message ID."
},
"metadata": {
"type": "object",
"description": "Metadata including usage and retriever resources.",
"properties": {
"usage": {
"$ref": "#/components/schemas/Usage"
},
"retriever_resources": {
"type": "array",
"description": "List of retriever resources used.",
"items": {
"$ref": "#/components/schemas/RetrieverResource"
}
}
}
}
}
}
]
},
"StreamEventChatMessageReplace": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Message content replacement event (e.g., due to content moderation).",
"properties": {
"answer": {
"type": "string",
"description": "Replacement content."
},
"reason": {
"type": "string",
"description": "Reason for the content replacement."
}
}
}
]
},
"StreamEventChatError": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Error event during streaming.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code."
},
"code": {
"type": "string",
"description": "Error code."
},
"message": {
"type": "string",
"description": "Error message."
}
}
}
]
},
"StreamEventChatPing": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"type": "object",
"description": "Ping event to keep connection alive. Delivered as an `event: ping` line with no `data:` payload."
}
]
},
"Usage": {
"type": "object",
"description": "Model usage information.",
"properties": {
"prompt_tokens": {
"type": "integer",
"description": "Number of tokens in the prompt."
},
"prompt_unit_price": {
"type": "string",
"format": "decimal",
"description": "Unit price per prompt token."
},
"prompt_price_unit": {
"type": "string",
"format": "decimal",
"description": "Price unit for prompt tokens."
},
"prompt_price": {
"type": "string",
"format": "decimal",
"description": "Total price for prompt tokens."
},
"completion_tokens": {
"type": "integer",
"description": "Number of tokens in the completion."
},
"completion_unit_price": {
"type": "string",
"format": "decimal",
"description": "Unit price per completion token."
},
"completion_price_unit": {
"type": "string",
"format": "decimal",
"description": "Price unit for completion tokens."
},
"completion_price": {
"type": "string",
"format": "decimal",
"description": "Total price for completion tokens."
},
"total_tokens": {
"type": "integer",
"description": "Total number of tokens used."
},
"total_price": {
"type": "string",
"format": "decimal",
"description": "Total price for all tokens."
},
"currency": {
"type": "string",
"description": "Currency for pricing."
},
"latency": {
"type": "number",
"format": "double",
"description": "Latency in seconds."
}
}
},
"RetrieverResource": {
"type": "object",
"description": "Citation and attribution information for a retriever resource.",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique ID of the retriever resource."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "ID of the message this resource belongs to."
},
"position": {
"type": "integer",
"description": "Position of the resource in the list."
},
"dataset_id": {
"type": "string",
"format": "uuid",
"description": "ID of the knowledge base."
},
"dataset_name": {
"type": "string",
"description": "Name of the knowledge base."
},
"document_id": {
"type": "string",
"format": "uuid",
"description": "ID of the document."
},
"document_name": {
"type": "string",
"description": "Name of the document."
},
"data_source_type": {
"type": "string",
"description": "Type of the data source."
},
"segment_id": {
"type": "string",
"format": "uuid",
"description": "ID of the specific chunk within the document."
},
"score": {
"type": "number",
"format": "float",
"description": "Similarity score of the resource."
},
"hit_count": {
"type": "integer",
"description": "Number of times this chunk was hit."
},
"word_count": {
"type": "integer",
"description": "Word count of the chunk."
},
"segment_position": {
"type": "integer",
"description": "Position of the chunk within the document."
},
"index_node_hash": {
"type": "string",
"description": "Hash of the index node."
},
"content": {
"type": "string",
"description": "Content snippet from the resource."
},
"summary": {
"type": "string",
"nullable": true,
"description": "Summary of the chunk content."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Creation timestamp (Unix epoch seconds)."
}
}
},
"FileUploadResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique file ID."
},
"name": {
"type": "string",
"description": "File name."
},
"size": {
"type": "integer",
"description": "File size in bytes."
},
"extension": {
"type": "string",
"nullable": true,
"description": "File extension."
},
"mime_type": {
"type": "string",
"nullable": true,
"description": "MIME type of the file."
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "ID of the user who uploaded the file."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Upload timestamp (Unix epoch seconds)."
},
"preview_url": {
"type": "string",
"nullable": true,
"description": "Preview URL for the file."
},
"source_url": {
"type": "string",
"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/chatflows/send-chat-message))."
},
"name": {
"type": "string",
"nullable": true,
"description": "End user name."
},
"is_anonymous": {
"type": "boolean",
"description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request."
},
"session_id": {
"type": "string",
"description": "Session identifier. Defaults to the `external_user_id` value."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp."
}
}
},
"MessageFeedbackRequest": {
"type": "object",
"description": "Request body for submitting message feedback.",
"required": [
"user"
],
"properties": {
"rating": {
"type": "string",
"enum": [
"like",
"dislike",
null
],
"nullable": true,
"description": "Feedback rating. Set to `null` to revoke previously submitted feedback."
},
"user": {
"type": "string",
"description": "User identifier, defined by the developer, must ensure uniqueness within the application."
},
"content": {
"type": "string",
"description": "Optional text feedback providing additional detail."
}
}
},
"AppFeedbacksResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "List of feedback items.",
"items": {
"$ref": "#/components/schemas/FeedbackItem"
}
}
}
},
"FeedbackItem": {
"type": "object",
"description": "A single feedback item.",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Feedback ID."
},
"app_id": {
"type": "string",
"format": "uuid",
"description": "Application ID."
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "Conversation ID."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Message ID."
},
"rating": {
"type": "string",
"description": "Feedback rating. `like` for positive, `dislike` for negative."
},
"content": {
"type": "string",
"nullable": true,
"description": "Optional text feedback."
},
"from_source": {
"type": "string",
"description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console."
},
"from_end_user_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "End user ID who submitted the feedback. Present when `from_source` is `user`."
},
"from_account_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Account ID who submitted the feedback. Present when `from_source` is `admin`."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp."
}
}
},
"SuggestedQuestionsResponse": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "Result status."
},
"data": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of suggested questions."
}
}
},
"ConversationHistoryResponse": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Number of items per page."
},
"has_more": {
"type": "boolean",
"description": "Whether there are more messages."
},
"data": {
"type": "array",
"description": "List of messages.",
"items": {
"$ref": "#/components/schemas/ConversationMessageItem"
}
}
}
},
"ConversationMessageItem": {
"type": "object",
"description": "A single message in a conversation.",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Message ID."
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "Conversation ID."
},
"parent_message_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Parent message ID for threaded conversations."
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "Input variables for this message."
},
"query": {
"type": "string",
"description": "User query text."
},
"answer": {
"type": "string",
"description": "Assistant answer text."
},
"status": {
"type": "string",
"description": "Message status. `normal` for successful messages, `error` when generation failed."
},
"error": {
"type": "string",
"nullable": true,
"description": "Error message if `status` is `error`."
},
"message_files": {
"type": "array",
"description": "Files attached to this message.",
"items": {
"$ref": "#/components/schemas/MessageFileItem"
}
},
"feedback": {
"type": "object",
"nullable": true,
"description": "User feedback for this message.",
"properties": {
"rating": {
"type": "string",
"description": "Feedback rating. `like` for positive, `dislike` for negative."
}
}
},
"retriever_resources": {
"type": "array",
"description": "Retriever resources used for this message.",
"items": {
"$ref": "#/components/schemas/RetrieverResource"
}
},
"agent_thoughts": {
"type": "array",
"description": "Agent thoughts for this message.",
"items": {
"$ref": "#/components/schemas/AgentThoughtItem"
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Creation timestamp (Unix epoch seconds)."
},
"extra_contents": {
"type": "array",
"description": "Additional execution content associated with this message, such as human input form data from Human Input nodes in Chatflow workflows.",
"items": {
"$ref": "#/components/schemas/HumanInputContent"
}
}
}
},
"MessageFileItem": {
"type": "object",
"description": "A file attached to a message.",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "File ID."
},
"filename": {
"type": "string",
"description": "Original filename."
},
"type": {
"type": "string",
"description": "File type, e.g., `image`."
},
"url": {
"type": "string",
"format": "url",
"nullable": true,
"description": "Preview URL for the file."
},
"mime_type": {
"type": "string",
"nullable": true,
"description": "MIME type of the file."
},
"size": {
"type": "integer",
"nullable": true,
"description": "File size in bytes."
},
"transfer_method": {
"type": "string",
"description": "Transfer method used. `remote_url` for URL-based files, `local_file` for uploaded files, `tool_file` for tool-generated files."
},
"belongs_to": {
"type": "string",
"nullable": true,
"description": "Who this file belongs to. `user` for user-uploaded files, `assistant` for assistant-generated files."
},
"upload_file_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Upload file ID if transferred via `local_file`."
}
}
},
"AgentThoughtItem": {
"type": "object",
"description": "An agent thought step in the message.",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Agent thought ID."
},
"chain_id": {
"type": "string",
"nullable": true,
"description": "Chain ID for this thought."
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "Unique message ID this thought belongs to."
},
"position": {
"type": "integer",
"description": "Position of this thought."
},
"thought": {
"type": "string",
"description": "What LLM is thinking."
},
"tool": {
"type": "string",
"description": "Tools called, split by `;`."
},
"tool_labels": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Labels for tools used."
},
"tool_input": {
"type": "string",
"description": "Input of tools in JSON format."
},
"observation": {
"type": "string",
"description": "Response from tool calls."
},
"files": {
"type": "array",
"items": {
"type": "string"
},
"description": "File IDs related to this thought."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Creation timestamp."
}
}
},
"ConversationsListResponse": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Number of items per page."
},
"has_more": {
"type": "boolean",
"description": "Whether there are more conversations."
},
"data": {
"type": "array",
"description": "List of conversations.",
"items": {
"$ref": "#/components/schemas/ConversationListItem"
}
}
}
},
"ConversationListItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Conversation ID."
},
"name": {
"type": "string",
"description": "Conversation name."
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "Input variables for the conversation."
},
"status": {
"type": "string",
"description": "Conversation status. `normal` for active conversations."
},
"introduction": {
"type": "string",
"description": "Conversation introduction."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Creation timestamp."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Last update timestamp."
}
}
},
"ConversationRenameRequest": {
"type": "object",
"description": "Request body for renaming a conversation.",
"required": [
"user"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the conversation. Required when `auto_generate` is `false`."
},
"auto_generate": {
"type": "boolean",
"default": false,
"description": "Automatically generate the conversation name. When `true`, the `name` field is ignored."
},
"user": {
"type": "string",
"description": "The user identifier."
}
}
},
"ConversationVariablesResponse": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Number of items per page."
},
"has_more": {
"type": "boolean",
"description": "Whether there is a next page."
},
"data": {
"type": "array",
"description": "List of conversation variables.",
"items": {
"$ref": "#/components/schemas/ConversationVariableItem"
}
}
}
},
"ConversationVariableItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Variable ID."
},
"name": {
"type": "string",
"description": "Variable name."
},
"value_type": {
"type": "string",
"description": "Variable value type. Possible values: `string`, `number`, `object`, `secret`, `file`, `boolean`, `array[any]`, `array[string]`, `array[number]`, `array[object]`, `array[file]`, `array[boolean]`."
},
"value": {
"type": "string",
"description": "Variable value (can be a JSON string for complex types)."
},
"description": {
"type": "string",
"description": "Variable description."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Creation timestamp."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Last update timestamp."
}
}
},
"ConversationVariableUpdateRequest": {
"type": "object",
"description": "Request body for updating a conversation variable.",
"required": [
"value"
],
"properties": {
"value": {
"description": "The new value for the variable. Must match the variable's expected type."
},
"user": {
"type": "string",
"description": "User identifier."
}
}
},
"AudioToTextRequest": {
"type": "object",
"description": "Request body for audio-to-text conversion.",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "Audio file. 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."
}
}
},
"ChatAppParametersResponse": {
"type": "object",
"properties": {
"opening_statement": {
"type": "string",
"description": "Opening statement displayed at conversation start."
},
"suggested_questions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of suggested starter questions."
},
"suggested_questions_after_answer": {
"type": "object",
"description": "Configuration for suggested questions after answer.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether this feature is enabled."
}
}
},
"speech_to_text": {
"type": "object",
"description": "Speech-to-text configuration.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether this feature is enabled."
}
}
},
"text_to_speech": {
"type": "object",
"description": "Text-to-speech configuration.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether this feature is enabled."
},
"voice": {
"type": "string",
"description": "Voice identifier for TTS."
},
"language": {
"type": "string",
"description": "Language for TTS."
},
"autoPlay": {
"type": "string",
"description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play."
}
}
},
"retriever_resource": {
"type": "object",
"description": "Retriever resource configuration.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether this feature is enabled."
}
}
},
"annotation_reply": {
"type": "object",
"description": "Annotation reply configuration.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether this feature is enabled."
}
}
},
"more_like_this": {
"type": "object",
"description": "More-like-this configuration.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether this feature is enabled."
}
}
},
"sensitive_word_avoidance": {
"type": "object",
"description": "Sensitive word avoidance configuration.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether this feature is enabled."
}
}
},
"user_input_form": {
"type": "array",
"description": "List of user input form elements.",
"items": {
"$ref": "#/components/schemas/UserInputFormItem"
}
},
"file_upload": {
"type": "object",
"description": "File upload configuration.",
"properties": {
"image": {
"type": "object",
"description": "Image upload settings.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether image upload is enabled."
},
"number_limits": {
"type": "integer",
"description": "Maximum number of images."
},
"detail": {
"type": "string",
"description": "Image detail level."
},
"transfer_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed transfer methods."
}
}
}
}
},
"system_parameters": {
"type": "object",
"description": "System-level parameters and limits.",
"properties": {
"file_size_limit": {
"type": "integer",
"description": "Maximum file size in MB."
},
"image_file_size_limit": {
"type": "integer",
"description": "Maximum image file size in MB."
},
"audio_file_size_limit": {
"type": "integer",
"description": "Maximum audio file size in MB."
},
"video_file_size_limit": {
"type": "integer",
"description": "Maximum video file size in MB."
},
"workflow_file_upload_limit": {
"type": "integer",
"description": "Maximum number of files for workflow file upload."
}
}
}
}
},
"UserInputFormItem": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/TextInputControlWrapper"
},
{
"$ref": "#/components/schemas/ParagraphControlWrapper"
},
{
"$ref": "#/components/schemas/SelectControlWrapper"
}
]
},
"TextInputControlWrapper": {
"title": "Text Input",
"type": "object",
"properties": {
"text-input": {
"$ref": "#/components/schemas/TextInputControl"
}
}
},
"ParagraphControlWrapper": {
"title": "Paragraph",
"type": "object",
"properties": {
"paragraph": {
"$ref": "#/components/schemas/ParagraphControl"
}
}
},
"SelectControlWrapper": {
"title": "Select",
"type": "object",
"properties": {
"select": {
"$ref": "#/components/schemas/SelectControl"
}
}
},
"TextInputControl": {
"type": "object",
"description": "Text input form control.",
"properties": {
"label": {
"type": "string",
"description": "Display label."
},
"variable": {
"type": "string",
"description": "Variable name."
},
"required": {
"type": "boolean",
"description": "Whether input is required."
},
"default": {
"type": "string",
"description": "Default value."
}
}
},
"ParagraphControl": {
"type": "object",
"description": "Paragraph (multi-line text) form control.",
"properties": {
"label": {
"type": "string",
"description": "Display label."
},
"variable": {
"type": "string",
"description": "Variable name."
},
"required": {
"type": "boolean",
"description": "Whether input is required."
},
"default": {
"type": "string",
"description": "Default value."
}
}
},
"SelectControl": {
"type": "object",
"description": "Select (dropdown) form control.",
"properties": {
"label": {
"type": "string",
"description": "Display label."
},
"variable": {
"type": "string",
"description": "Variable name."
},
"required": {
"type": "boolean",
"description": "Whether selection is required."
},
"default": {
"type": "string",
"description": "Default selected value."
},
"options": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of selectable values for this form control."
}
}
},
"AppMetaResponse": {
"type": "object",
"properties": {
"tool_icons": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"title": "Icon URL",
"type": "string",
"format": "url",
"description": "URL of the icon."
},
{
"$ref": "#/components/schemas/ToolIconDetail"
}
]
},
"description": "Tool icons. Keys are tool names."
}
}
},
"ToolIconDetail": {
"title": "Emoji Icon",
"type": "object",
"description": "Detail of a tool icon using emoji.",
"properties": {
"background": {
"type": "string",
"description": "Background color in hex format."
},
"content": {
"type": "string",
"description": "Emoji content."
}
}
},
"WebAppSettingsResponse": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "WebApp title."
},
"chat_color_theme": {
"type": "string",
"description": "Chat color theme."
},
"chat_color_theme_inverted": {
"type": "boolean",
"description": "Whether the chat color theme is inverted."
},
"icon_type": {
"type": "string",
"description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons."
},
"icon": {
"type": "string",
"description": "Icon content (emoji or image ID)."
},
"icon_background": {
"type": "string",
"description": "Icon background color."
},
"icon_url": {
"type": "string",
"format": "url",
"nullable": true,
"description": "URL of the icon image."
},
"description": {
"type": "string",
"description": "WebApp description."
},
"copyright": {
"type": "string",
"description": "Copyright text."
},
"privacy_policy": {
"type": "string",
"description": "Privacy policy URL."
},
"custom_disclaimer": {
"type": "string",
"description": "Custom disclaimer text."
},
"default_language": {
"type": "string",
"description": "Default language code."
},
"show_workflow_steps": {
"type": "boolean",
"description": "Whether to show workflow steps."
},
"use_icon_as_answer_icon": {
"type": "boolean",
"description": "Whether to use the app icon as the answer icon."
}
}
},
"AnnotationListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AnnotationItem"
},
"description": "List of annotation items for the current page."
},
"has_more": {
"type": "boolean",
"description": "`true` if more pages are available beyond the current result set."
},
"limit": {
"type": "integer",
"description": "Number of items per page."
},
"total": {
"type": "integer",
"description": "Total number of annotations matching the query."
},
"page": {
"type": "integer",
"description": "Current page number."
}
}
},
"AnnotationItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique annotation identifier."
},
"question": {
"type": "string",
"nullable": true,
"description": "Question text that triggers this annotation."
},
"answer": {
"type": "string",
"nullable": true,
"description": "Predefined answer returned when the annotation is matched."
},
"hit_count": {
"type": "integer",
"nullable": true,
"description": "Number of times this annotation has been matched and returned as a reply."
},
"created_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Creation timestamp (Unix epoch seconds)."
}
}
},
"CreateAnnotationRequest": {
"type": "object",
"description": "Request body for creating a new annotation.",
"required": [
"question",
"answer"
],
"properties": {
"question": {
"type": "string",
"description": "Annotation question."
},
"answer": {
"type": "string",
"description": "Annotation answer."
}
}
},
"UpdateAnnotationRequest": {
"type": "object",
"description": "Request body for updating an annotation.",
"required": [
"question",
"answer"
],
"properties": {
"question": {
"type": "string",
"description": "Updated annotation question."
},
"answer": {
"type": "string",
"description": "Updated annotation answer."
}
}
},
"InitialAnnotationReplySettingsRequest": {
"type": "object",
"description": "Request body for configuring annotation reply settings.",
"required": [
"score_threshold",
"embedding_provider_name",
"embedding_model_name"
],
"properties": {
"embedding_provider_name": {
"type": "string",
"description": "Name of the embedding model provider (e.g., `openai`, `cohere`)."
},
"embedding_model_name": {
"type": "string",
"description": "Name of the embedding model to use for annotation matching (e.g., `text-embedding-3-small`)."
},
"score_threshold": {
"type": "number",
"format": "float",
"description": "Minimum similarity score for an annotation to be considered a match. Higher values require closer matches."
}
}
},
"InitialAnnotationReplySettingsResponse": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"format": "uuid",
"description": "Asynchronous job ID. Use with [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress."
},
"job_status": {
"type": "string",
"description": "Current job status: `waiting` (queued) or `processing` (in progress). `completed` and `error` are returned only by [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status)."
}
}
},
"InitialAnnotationReplySettingsStatusResponse": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"format": "uuid",
"description": "Job ID from the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call."
},
"job_status": {
"type": "string",
"description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed."
},
"error_msg": {
"type": "string",
"description": "Error message describing why the job failed. Empty string when `job_status` is not `error`."
}
}
},
"StreamEventWorkflowStarted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Workflow execution started.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Workflow run ID."
},
"workflow_id": {
"type": "string",
"description": "Associated workflow ID."
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "Input variables for this workflow execution."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Start timestamp (Unix epoch seconds)."
},
"reason": {
"type": "string",
"description": "Reason for workflow start. `initial` for first start, `resumption` when resuming after a pause (e.g., after human input)."
}
}
}
}
}
]
},
"StreamEventWorkflowFinished": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Workflow execution finished.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Workflow run ID."
},
"workflow_id": {
"type": "string",
"description": "Associated workflow ID."
},
"status": {
"type": "string",
"description": "Execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `stopped` if manually stopped, `partial-succeeded` if partially completed, `paused` when waiting for human input."
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Workflow output data."
},
"error": {
"type": "string",
"nullable": true,
"description": "Error message if execution failed."
},
"elapsed_time": {
"type": "number",
"description": "Total execution time in seconds."
},
"total_tokens": {
"type": "integer",
"description": "Total tokens consumed."
},
"total_steps": {
"type": "integer",
"description": "Total steps executed."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Start timestamp (Unix epoch seconds)."
},
"finished_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Finish timestamp (Unix epoch seconds)."
},
"exceptions_count": {
"type": "integer",
"nullable": true,
"description": "Number of exceptions during execution."
},
"files": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Files generated during workflow execution."
}
}
}
}
}
]
},
"StreamEventNodeStarted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Node execution started.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Node execution ID."
},
"node_id": {
"type": "string",
"description": "Node ID in the workflow graph."
},
"node_type": {
"type": "string",
"description": "Node type (e.g., `llm`, `knowledge-retrieval`, `code`)."
},
"title": {
"type": "string",
"description": "Node title."
},
"index": {
"type": "integer",
"description": "Execution index."
},
"predecessor_node_id": {
"type": "string",
"nullable": true,
"description": "ID of the predecessor node."
},
"inputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Node input data. May be `null` in simplified API responses."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Start timestamp (Unix epoch seconds)."
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "Additional metadata."
},
"iteration_id": {
"type": "string",
"nullable": true,
"description": "Iteration ID if this node runs inside an iteration."
},
"loop_id": {
"type": "string",
"nullable": true,
"description": "Loop ID if this node runs inside a loop."
}
}
}
}
}
]
},
"StreamEventNodeFinished": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Node execution finished.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Node execution ID."
},
"node_id": {
"type": "string",
"description": "Node ID in the workflow graph."
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Node title."
},
"index": {
"type": "integer",
"description": "Execution index."
},
"predecessor_node_id": {
"type": "string",
"nullable": true,
"description": "ID of the predecessor node."
},
"inputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Node input data. May be `null` in simplified API responses."
},
"process_data": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Node processing data. May be `null` in simplified API responses."
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Node output data. May be `null` in simplified API responses."
},
"status": {
"type": "string",
"description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred."
},
"error": {
"type": "string",
"nullable": true,
"description": "Error message if node failed."
},
"elapsed_time": {
"type": "number",
"description": "Node execution time in seconds."
},
"execution_metadata": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Execution metadata (e.g., token usage, model info). May be `null` in simplified API responses."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Start timestamp (Unix epoch seconds)."
},
"finished_at": {
"type": "integer",
"format": "int64",
"description": "Finish timestamp (Unix epoch seconds)."
},
"files": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Files generated by this node."
},
"iteration_id": {
"type": "string",
"nullable": true,
"description": "Iteration ID if this node runs inside an iteration."
},
"loop_id": {
"type": "string",
"nullable": true,
"description": "Loop ID if this node runs inside a loop."
}
}
}
}
}
]
},
"StreamEventNodeRetry": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Node retry attempt.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Node execution ID."
},
"node_id": {
"type": "string",
"description": "Node ID in the workflow graph."
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Node title."
},
"index": {
"type": "integer",
"description": "Execution index."
},
"predecessor_node_id": {
"type": "string",
"nullable": true,
"description": "ID of the predecessor node."
},
"inputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Node input data."
},
"process_data": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Node processing data."
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Node output data."
},
"status": {
"type": "string",
"description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred."
},
"error": {
"type": "string",
"nullable": true,
"description": "Error message for this retry attempt."
},
"elapsed_time": {
"type": "number",
"description": "Execution time for this attempt in seconds."
},
"execution_metadata": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Execution metadata."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Start timestamp (Unix epoch seconds)."
},
"finished_at": {
"type": "integer",
"format": "int64",
"description": "Finish timestamp (Unix epoch seconds)."
},
"files": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Files generated during this retry."
},
"iteration_id": {
"type": "string",
"nullable": true,
"description": "Iteration ID if applicable."
},
"loop_id": {
"type": "string",
"nullable": true,
"description": "Loop ID if applicable."
},
"retry_index": {
"type": "integer",
"description": "Retry attempt index, starts at `0`."
}
}
}
}
}
]
},
"StreamEventIterationStarted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Iteration loop started.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Iteration execution ID."
},
"node_id": {
"type": "string",
"description": "Iteration node ID."
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Iteration node title."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Start timestamp (Unix epoch seconds)."
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "Additional metadata."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Iteration metadata."
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "Iteration input data."
}
}
}
}
}
]
},
"StreamEventIterationNext": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Iteration progressed to next item.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Iteration execution ID."
},
"node_id": {
"type": "string",
"description": "Iteration node ID."
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Iteration node title."
},
"index": {
"type": "integer",
"description": "Current iteration index (0-based)."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Timestamp (Unix epoch seconds)."
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "Additional metadata."
}
}
}
}
}
]
},
"StreamEventIterationCompleted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Iteration loop completed.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Iteration execution ID."
},
"node_id": {
"type": "string",
"description": "Iteration node ID."
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Iteration node title."
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Iteration output data."
},
"status": {
"type": "string",
"description": "Iteration execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred."
},
"error": {
"type": "string",
"nullable": true,
"description": "Error message if iteration failed."
},
"elapsed_time": {
"type": "number",
"description": "Total iteration time in seconds."
},
"total_tokens": {
"type": "integer",
"description": "Total tokens consumed across all iterations."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Start timestamp (Unix epoch seconds)."
},
"finished_at": {
"type": "integer",
"format": "int64",
"description": "Finish timestamp (Unix epoch seconds)."
},
"steps": {
"type": "integer",
"description": "Total number of iteration steps executed."
}
}
}
}
}
]
},
"StreamEventLoopStarted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Loop started.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Loop execution ID."
},
"node_id": {
"type": "string",
"description": "Loop node ID."
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Loop node title."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Start timestamp (Unix epoch seconds)."
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "Additional metadata."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Loop metadata."
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "Loop input data."
}
}
}
}
}
]
},
"StreamEventLoopNext": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Loop progressed to next iteration.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Loop execution ID."
},
"node_id": {
"type": "string",
"description": "Loop node ID."
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Loop node title."
},
"index": {
"type": "integer",
"description": "Current loop index (0-based)."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Timestamp (Unix epoch seconds)."
},
"pre_loop_output": {
"description": "Output from the previous loop iteration."
},
"extras": {
"type": "object",
"additionalProperties": true,
"description": "Additional metadata."
}
}
}
}
}
]
},
"StreamEventLoopCompleted": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Loop completed.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Loop execution ID."
},
"node_id": {
"type": "string",
"description": "Loop node ID."
},
"node_type": {
"type": "string",
"description": "Node type."
},
"title": {
"type": "string",
"description": "Loop node title."
},
"outputs": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Loop output data."
},
"status": {
"type": "string",
"description": "Loop execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred."
},
"error": {
"type": "string",
"nullable": true,
"description": "Error message if loop failed."
},
"elapsed_time": {
"type": "number",
"description": "Total loop execution time in seconds."
},
"total_tokens": {
"type": "integer",
"description": "Total tokens consumed across all loop iterations."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Start timestamp (Unix epoch seconds)."
},
"finished_at": {
"type": "integer",
"format": "int64",
"description": "Finish timestamp (Unix epoch seconds)."
},
"steps": {
"type": "integer",
"description": "Total number of loop steps executed."
}
}
}
}
}
]
},
"StreamEventHumanInputRequired": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"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."
}
}
}
}
}
]
},
"StreamEventWorkflowPaused": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/chatflows/get-workflow-run-detail) to retrieve results after execution."
},
"paused_nodes": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of paused node IDs."
},
"outputs": {
"type": "object",
"additionalProperties": true,
"description": "Partial outputs at pause time."
},
"reasons": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Reasons for pausing."
},
"status": {
"type": "string",
"description": "Workflow execution status."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Creation timestamp."
},
"elapsed_time": {
"type": "number",
"format": "float",
"description": "Total elapsed time in seconds."
},
"total_tokens": {
"type": "integer",
"description": "Total tokens consumed."
},
"total_steps": {
"type": "integer",
"description": "Total steps executed."
}
}
}
}
}
]
},
"StreamEventHumanInputFormFilled": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"description": "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/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "Workflow execution run ID."
},
"data": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"description": "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."
}
}
}
}
}
]
},
"StreamEventAgentLog": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Agent log from an agent node within the workflow.",
"properties": {
"data": {
"type": "object",
"properties": {
"node_execution_id": {
"type": "string",
"description": "Node execution ID."
},
"id": {
"type": "string",
"description": "Log entry ID."
},
"label": {
"type": "string",
"description": "Log entry label."
},
"parent_id": {
"type": "string",
"nullable": true,
"description": "Parent log entry ID for nested entries."
},
"error": {
"type": "string",
"nullable": true,
"description": "Error message if applicable."
},
"status": {
"type": "string",
"description": "Log entry status."
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "Log entry data."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Additional metadata."
},
"node_id": {
"type": "string",
"description": "Node ID in the workflow graph."
}
}
}
}
}
]
},
"StreamEventChatReasoningChunk": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message_id": {
"type": "string",
"format": "uuid",
"description": "ID of the message this reasoning belongs to (mirrors the top-level `message_id`)."
},
"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 `message`; the `message` (answer) 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`."
}
}
}
}
}
]
},
"StreamEventChatTextChunk": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The text content chunk."
},
"from_variable_selector": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "Source path of the text variable in the workflow."
}
}
}
}
}
]
},
"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."
}
}
},
"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."
}
}
},
"HumanInputContent": {
"type": "object",
"description": "Execution content from a Human Input node, including form definition and submission data.",
"properties": {
"workflow_run_id": {
"type": "string",
"description": "ID of the workflow run this content belongs to."
},
"submitted": {
"type": "boolean",
"description": "Whether the human input form has been submitted."
},
"type": {
"type": "string",
"description": "`human_input` for human input content."
},
"form_definition": {
"nullable": true,
"description": "Form definition from the Human Input node. `null` when the content represents a submission response.",
"$ref": "#/components/schemas/HumanInputFormDefinition"
},
"form_submission_data": {
"nullable": true,
"description": "Submitted form data. `null` when the form has not been submitted yet.",
"$ref": "#/components/schemas/HumanInputFormSubmissionData"
}
}
},
"HumanInputFormDefinition": {
"type": "object",
"description": "Definition of a human input form rendered by a Human Input node.",
"properties": {
"form_id": {
"type": "string",
"description": "Unique form identifier."
},
"node_id": {
"type": "string",
"description": "ID of the Human Input node that generated this form."
},
"node_title": {
"type": "string",
"description": "Title of the Human Input node."
},
"form_content": {
"type": "string",
"description": "Markdown or text content displayed with the form."
},
"inputs": {
"type": "array",
"description": "Input fields in the form.",
"items": {
"$ref": "#/components/schemas/FormInput"
}
},
"actions": {
"type": "array",
"description": "Action buttons available on the form.",
"items": {
"$ref": "#/components/schemas/UserAction"
}
},
"display_in_ui": {
"type": "boolean",
"description": "Whether the form should be displayed in the UI."
},
"form_token": {
"type": "string",
"nullable": true,
"description": "Token for form submission authentication."
},
"resolved_default_values": {
"type": "object",
"additionalProperties": true,
"description": "Resolved default values for form inputs, keyed by output variable name."
},
"expiration_time": {
"type": "integer",
"description": "Unix timestamp when the form expires."
}
}
},
"HumanInputFormSubmissionData": {
"type": "object",
"description": "Data from a submitted human input form.",
"properties": {
"node_id": {
"type": "string",
"description": "ID of the Human Input node."
},
"node_title": {
"type": "string",
"description": "Title of the Human Input node."
},
"rendered_content": {
"type": "string",
"description": "Rendered content of the form submission."
},
"action_id": {
"type": "string",
"description": "ID of the action button that was clicked."
},
"action_text": {
"type": "string",
"description": "Display text of the action button that was clicked."
}
}
},
"FormInput": {
"type": "object",
"description": "A form input field definition.",
"properties": {
"type": {
"type": "string",
"description": "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 where the input value is stored."
},
"default": {
"nullable": true,
"description": "Default value configuration for this input.",
"$ref": "#/components/schemas/FormInputDefault"
}
}
},
"FormInputDefault": {
"type": "object",
"description": "Default value configuration for a form input.",
"properties": {
"type": {
"type": "string",
"description": "`variable` for dynamic values from workflow variables, `constant` for static values."
},
"selector": {
"type": "array",
"items": {
"type": "string"
},
"description": "Variable selector path when `type` is `variable`."
},
"value": {
"type": "string",
"description": "Static value when `type` is `constant`."
}
}
},
"UserAction": {
"type": "object",
"description": "An action button on a human input form.",
"properties": {
"id": {
"type": "string",
"description": "Unique action identifier."
},
"title": {
"type": "string",
"description": "Button display text."
},
"button_style": {
"type": "string",
"description": "`primary`, `default`, `accent`, or `ghost`."
}
}
}
}
},
"tags": [
{
"name": "Chatflows",
"description": "Operations for Chatflow apps, including chat messaging, workflow run details, and event streaming."
},
{
"name": "Files",
"description": "File upload and preview operations."
},
{
"name": "End Users",
"description": "Operations related to end user information."
},
{
"name": "Feedback",
"description": "User feedback operations."
},
{
"name": "Conversations",
"description": "Operations related to managing conversations."
},
{
"name": "TTS",
"description": "Text-to-Speech and Speech-to-Text operations."
},
{
"name": "Applications",
"description": "Operations to retrieve application settings and information."
},
{
"name": "Annotations",
"description": "Operations related to managing annotations for direct replies."
},
{
"name": "Human Input",
"description": "Endpoints for resuming paused workflows that require human input."
}
]
}
Reference in New Issue View Git Blame Copy Permalink