{ "openapi": "3.0.1", "info": { "title": "Dify Service API", "description": "REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key.", "version": "1.0.0" }, "servers": [ { "url": "https://{api_base_url}", "description": "Base URL of the Dify Service 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": [] } ], "tags": [ { "name": "Chat Messages", "description": "Operations related to chat messages and interactions." }, { "name": "Files", "description": "File upload and preview operations." }, { "name": "End Users", "description": "Operations related to end user information." }, { "name": "Feedback", "description": "User feedback operations." }, { "name": "Conversations", "description": "Operations related to managing conversations." }, { "name": "Audio", "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." }, { "name": "Workflow Runs", "description": "Operations for executing and managing workflows." }, { "name": "Completion Messages", "description": "Operations related to text generation and completion." }, { "name": "Knowledge Bases", "description": "Operations for managing knowledge bases, including creation, configuration, and retrieval." }, { "name": "Documents", "description": "Operations for creating, updating, and managing documents within a knowledge base." }, { "name": "Chunks", "description": "Operations for managing document chunks and child chunks." }, { "name": "Metadata", "description": "Operations for managing knowledge base metadata fields and document metadata values." }, { "name": "Tags", "description": "Operations for managing knowledge base tags and tag bindings." }, { "name": "Models", "description": "Operations for retrieving available models." }, { "name": "Knowledge Pipeline", "description": "Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution." } ], "paths": { "/chat-messages": { "post": { "summary": "Send Chat Message", "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nSends a message to a chat app and returns the assistant's reply. The events in the streaming response vary by app type.", "operationId": "sendChatMessage", "tags": [ "Chat Messages" ], "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": "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. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive; a Chatflow stream opens with one, then more arrive roughly every 10 seconds).\n\n**Events by app type** (the reply events, then how the stream closes):\n\n- **Chatbot**: `message` chunks (concatenate in order) → `message_end`.\n- **Legacy Agent**: `agent_thought` reasoning and tool-call steps alongside `agent_message` chunks → `message_end`.\n- **Agent**: `agent_message` chunks with `agent_thought` steps alongside → one closing `message` carrying the complete answer (treat it as the final answer, not extra text to append) → `message_end`. Its `message_end` metadata carries `usage` (plus `annotation_reply` on an annotation match) and never `retriever_resources`.\n- **Chatflow**: `workflow_started` → node events (`node_started`, `node_finished`, plus iteration and loop variants) alongside `message` chunks → then, by 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\n**Add-ons**:\n\n- Text-to-speech auto-play: `tts_message` audio chunks interleave, and `tts_message_end` trails the closing event.\n- Chatflow LLM nodes with `reasoning_format: separated` also emit `reasoning_chunk` deltas carrying the model's reasoning.\n\n**Common fields**: 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 (Chatflow apps) nest their payload under `data` and, except for `agent_log`, carry a top-level `workflow_run_id`.\n\n**Reply events**\n\n| Event | App | Fires on | Key fields |\n|:---|:---|:---|:---|\n| `message` | Chatbot, Chatflow, Agent | each answer chunk (concatenate in order); for Agent, one closing chunk with the complete answer | `answer` |\n| `agent_message` | Legacy Agent, Agent | each answer chunk (concatenate in order) | `answer` |\n| `agent_thought` | Legacy Agent, Agent | each reasoning or tool-call step | `position`, `thought`, `tool`, `tool_input` (JSON), `observation`, `message_files` |\n| `message_replace` | All | output moderation replaces the answer so far | `answer`; Chatflow also `reason` |\n| `reasoning_chunk` | Chatflow | each reasoning-content delta, when an LLM node uses `reasoning_format: separated` (concatenate in order; a final `is_final: true` event marks reasoning finished and may carry an empty `reasoning`) | `data.message_id`, `data.reasoning`, `data.node_id`, `data.is_final` |\n| `message_file` | Chatbot, Legacy Agent | the assistant returns a file | `type`, `belongs_to`, `url` |\n| `message_end` | All | the answer is complete | `metadata` (`usage`, `retriever_resources`) |\n| `tts_message`, `tts_message_end` | Chatbot, Legacy Agent, Chatflow | audio chunk / end, when TTS auto-play is on | `audio` |\n\n**Workflow and node events** (Chatflow apps only)\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](/en/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](/en/api-reference/workflow-runs/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; opens every Chatflow stream, then roughly 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}\n\ndata: {\"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}}}" }, "streamingResponseAgent": { "summary": "Response Example - Streaming (Agent)", "value": "data: {\"event\": \"agent_thought\", \"id\": \"agent_thought_id_1\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"position\": 1, \"thought\": \"Thinking about calling a tool...\", \"tool\": \"dalle3\", \"tool_input\": \"{\\\"dalle3\\\": {\\\"prompt\\\": \\\"a cute cat\\\"}}\", \"created_at\": 1705395332}\n\ndata: {\"event\": \"message_file\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"created_at\": 1705395332}\n\ndata: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333}\n\ndata: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}" }, "streamingResponseWorkflow": { "summary": "Response Example - Streaming (Workflow)", "value": "event: ping\n\ndata: {\"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}}\n\ndata: {\"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}}\n\ndata: {\"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}}\n\ndata: {\"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}}\n\ndata: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333}\n\ndata: {\"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}}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}\n\ndata: {\"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": "event: ping\n\ndata: {\"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\"}}\n\ndata: {\"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}}\n\ndata: {\"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.\n- `bad_request` : `blocking` response mode with an Agent app.\n- `invalid_param` : The Agent app has no bound Agent.\n- `agent_not_published` : The bound Agent has no published version. (Agent apps)\n- `conversation_completed` : The conversation has ended; start a new one by omitting `conversation_id`.", "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'. " } }, "new_agent_streaming_only": { "summary": "bad_request", "value": { "code": "bad_request", "message": "Agent App only supports streaming response mode.", "status": 400 } }, "new_agent_not_bound": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Agent App has no bound Agent", "status": 400 } }, "new_agent_not_published": { "summary": "agent_not_published", "value": { "code": "agent_not_published", "message": "Agent has not been published. Please publish the Agent before using the API.", "status": 400 } }, "conversation_completed": { "summary": "conversation_completed", "value": { "status": 400, "code": "conversation_completed", "message": "The conversation has ended. Please start a new conversation." } } } } } }, "403": { "description": "`workflow_version_execution_not_allowed` : A Chatflow request pinned a workflow version via `workflow_id` on the Dify Cloud Sandbox plan.", "content": { "application/json": { "examples": { "workflow_version_execution_not_allowed": { "summary": "workflow_version_execution_not_allowed", "value": { "status": 403, "code": "workflow_version_execution_not_allowed", "message": "Workflow version execution is not available on your current plan. Please upgrade to a paid plan." } } } } } }, "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 workspace's Dify Cloud quota for workflow executions has been exhausted.", "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": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "x-mint": { "href": "/en/api-reference/chat-messages/send-chat-message", "metadata": { "title": "Send Chat Message", "sidebarTitle": "Send Chat Message" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/chat-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"query\": \"What are the specs of the iPhone 13 Pro Max?\", \"inputs\": {}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'" } ] } }, "/chat-messages/{task_id}/stop": { "post": { "summary": "Stop Chat Message Generation", "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nStops a chat message generation task. Only supported in `streaming` mode.", "operationId": "stopChatMessageGeneration", "tags": [ "Chat Messages" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "Task ID, from the streaming events of [Send Chat Message](/en/api-reference/chat-messages/send-chat-message).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "End-user identifier, defined by your app and unique within it. Must match the `user` sent with the original message; if it differs, the stop silently does nothing and still returns success. See [End User Identity](/en/api-reference/guides/end-user-identity)." } } }, "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.\n- `invalid_param` : The required `user` field is missing.", "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." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } } }, "x-mint": { "href": "/en/api-reference/chat-messages/stop-chat-message-generation", "metadata": { "title": "Stop Chat Message Generation", "sidebarTitle": "Stop Chat Message Generation" } } } }, "/messages/{message_id}/suggested": { "get": { "summary": "Get Next Suggested Questions", "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nReturns the follow-up questions suggested for a message.", "operationId": "getSuggestedQuestions", "tags": [ "Chat Messages" ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "ID of the message to get suggestions for. Get it from a chat response or [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages).", "schema": { "type": "string", "format": "uuid" } }, { "name": "user", "in": "query", "required": true, "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "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": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "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}'" } ], "x-mint": { "href": "/en/api-reference/chat-messages/get-next-suggested-questions", "metadata": { "title": "Get Next Suggested Questions", "sidebarTitle": "Get Next Suggested Questions" } } } }, "/files/upload": { "post": { "summary": "Upload File", "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nUploads a file and returns its `id` for later requests to reference. The file belongs to the uploading end user: only requests carrying the same `user` can reference it.\n\nWhich file types an app actually consumes depends on its file-upload settings; read them from [Get App Parameters](/en/api-reference/applications/get-app-parameters).", "operationId": "uploadChatFile", "tags": [ "Files" ], "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 upload, as one `multipart/form-data` part. The filename must not contain `/` or `\\`.\n\nAny extension is accepted unless it is on the deployment's security blacklist (`UPLOAD_FILE_EXTENSION_BLACKLIST`, empty by default).\n\nSize limits per category: images 10 MB, audio 50 MB, video 100 MB, other files 15 MB by default (Dify Cloud uses the defaults). Self-hosted deployments adjust them with the `UPLOAD_*_FILE_SIZE_LIMIT` [environment variables](/en/self-host/deploy/configuration/environments)." }, "user": { "type": "string", "description": "End-user identifier this upload belongs to, defined by your app and unique within it. Omit it to attribute the upload to the shared `DEFAULT-USER`. Only later requests with the same `user` can reference the file. See [End User Identity](/en/api-reference/guides/end-user-identity)." } } } } } }, "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", "reference": null, "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 `/` or `\\`, or the file's extension is on the deployment's blacklist.", "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": "File extension '.exe' is not allowed for security reasons" } } } } } }, "413": { "description": "`file_too_large` : The file exceeds its category's size limit (see the `file` field). The runtime `message` is currently returned as an empty string (a known backend quirk); rely on the `code` and status.", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "" } } } } } }, "415": { "description": "`unsupported_file_type` : The uploaded `file` part declares no MIME type.", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "x-mint": { "href": "/en/api-reference/files/upload-file", "metadata": { "title": "Upload File", "sidebarTitle": "Upload File" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/files/upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@product-photo.png' \\\n --form 'user={user}'" } ] } }, "/files/{file_id}/preview": { "get": { "summary": "Download File", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns the raw bytes of a file previously returned by [Upload File](/en/api-reference/files/upload-file). A file is reachable only through the app whose messages reference it.", "operationId": "previewChatFile", "tags": [ "Files" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "ID of the file to download, from the Upload File response.", "schema": { "type": "string", "format": "uuid" } }, { "name": "as_attachment", "in": "query", "required": false, "description": "When `true`, the file downloads as an attachment instead of rendering inline in the browser.", "schema": { "type": "boolean", "default": false } }, { "name": "user", "in": "query", "required": false, "description": "End-user identifier, defined by your app and unique within it. It has no effect on file access here, which is scoped by app and message rather than by `user`. See [End User Identity](/en/api-reference/guides/end-user-identity).", "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` : The file exists but belongs to a different app or workspace.", "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` : No file with this ID is reachable through this app's messages.", "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/files/download-file", "metadata": { "title": "Download File", "sidebarTitle": "Download File" } } } }, "/end-users/{end_user_id}": { "get": { "summary": "Get End User Info", "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns an end user's details by ID. Useful for resolving an end-user ID returned by another endpoint, such as `created_by` in the [Upload File](/en/api-reference/files/upload-file) response.", "operationId": "getEndUserChat", "tags": [ "End Users" ], "parameters": [ { "name": "end_user_id", "in": "path", "required": true, "description": "ID of the end user to look up.", "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/end-users/get-end-user-info", "metadata": { "title": "Get End User Info", "sidebarTitle": "Get End User Info" } } } }, "/messages/{message_id}/feedbacks": { "post": { "summary": "Submit Message Feedback", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent, Text Generator apps.\n\nRecords a `like` or `dislike` rating, plus an optional comment, on a message. Submitting `null` for `rating` revokes the message's existing feedback.", "operationId": "postChatMessageFeedback", "tags": [ "Feedback" ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "ID of the message to give feedback on. Get message IDs from [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages).", "schema": { "type": "string", "format": "uuid" } } ], "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" }, "400": { "description": "`invalid_param` : The required `user` field is omitted, or `rating` is `null` but there is no existing feedback to revoke.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/feedback/submit-message-feedback", "metadata": { "title": "Submit Message Feedback", "sidebarTitle": "Submit Message Feedback" } } } }, "/app/feedbacks": { "get": { "summary": "List App Feedbacks", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns a paginated list of all feedback on the app's messages, including both end-user and admin submissions.", "operationId": "getChatAppFeedbacks", "tags": [ "Feedback" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Feedback items 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" } ] } } } } } } }, "x-mint": { "href": "/en/api-reference/feedback/list-app-feedbacks", "metadata": { "title": "List App Feedbacks", "sidebarTitle": "List App Feedbacks" } } } }, "/conversations": { "get": { "summary": "List Conversations", "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nLists an end user's conversations, most recently active first.", "operationId": "getConversationsList", "tags": [ "Conversations" ], "parameters": [ { "name": "user", "in": "query", "required": false, "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "schema": { "type": "string" } }, { "name": "last_id", "in": "query", "required": false, "description": "Pagination cursor: the `id` of the last conversation on the current page. Omit to fetch the first page.", "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": "Field to sort by. Prefix with `-` 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." } } } } } } }, "x-mint": { "href": "/en/api-reference/conversations/list-conversations", "metadata": { "title": "List Conversations", "sidebarTitle": "List Conversations" } } } }, "/messages": { "get": { "summary": "List Conversation Messages", "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nReturns a conversation's message history, newest first. Pass `first_id` to page backward into older messages.", "operationId": "getConversationHistory", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "query", "required": true, "description": "ID of the conversation to read. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "schema": { "type": "string" } }, { "name": "first_id", "in": "query", "required": false, "description": "Pagination cursor: the `id` of the first message on the current page. Pass it to fetch the previous (older) page; omit to fetch the latest 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, "extra_contents": [], "message_tokens": 100, "answer_tokens": 58, "total_tokens": 158, "provider_response_latency": 1.234, "total_price": "0.0012825", "currency": "USD" } ] } } } } } }, "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 (invalid `first_id`).", "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}'" } ], "x-mint": { "href": "/en/api-reference/conversations/list-conversation-messages", "metadata": { "title": "List Conversation Messages", "sidebarTitle": "List Conversation Messages" } } } }, "/conversations/{conversation_id}/variables": { "get": { "summary": "List Conversation Variables", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nLists the variables stored in a conversation.", "operationId": "getConversationVariables", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "ID of the conversation whose variables to list. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "schema": { "type": "string" } }, { "name": "last_id", "in": "query", "required": false, "description": "Pagination cursor: the `id` of the last variable on the current page. Omit to fetch the first page.", "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.\n- `invalid_param` : The `last_id` does not match any variable in this conversation.", "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." } }, "invalid_last_id": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "" } } } } } }, "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/conversations/list-conversation-variables", "metadata": { "title": "List Conversation Variables", "sidebarTitle": "List Conversation Variables" } } } }, "/conversations/{conversation_id}/name": { "post": { "summary": "Rename Conversation", "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nRenames a conversation, or auto-generates a name from its messages when `auto_generate` is `true`. The name is what clients display in a multi-conversation list.", "operationId": "renameConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "ID of the conversation to rename. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "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.\n- `invalid_param` : `auto_generate` is `true` but the conversation has no messages to generate a name from.", "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." } }, "no_messages": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "" } } } } } }, "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/conversations/rename-conversation", "metadata": { "title": "Rename Conversation", "sidebarTitle": "Rename Conversation" } } } }, "/conversations/{conversation_id}/variables/{variable_id}": { "put": { "summary": "Update Conversation Variable", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nUpdates a conversation variable's value. The new value must match the variable's existing type.", "operationId": "updateChatConversationVariable", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "ID of the conversation that owns the variable. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "schema": { "type": "string", "format": "uuid" } }, { "name": "variable_id", "in": "path", "required": true, "description": "ID of the variable to update. Get variable IDs from [List Conversation Variables](/en/api-reference/conversations/list-conversation-variables).", "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": "Type mismatch: variable 'user_preference' expects string, but got number type" } } } } } }, "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/conversations/update-conversation-variable", "metadata": { "title": "Update Conversation Variable", "sidebarTitle": "Update Conversation Variable" } } } }, "/conversations/{conversation_id}": { "delete": { "summary": "Delete Conversation", "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nDeletes a conversation.", "operationId": "deleteConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "ID of the conversation to delete. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "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": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)." } } }, "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/conversations/delete-conversation", "metadata": { "title": "Delete Conversation", "sidebarTitle": "Delete Conversation" } } } }, "/audio-to-text": { "post": { "summary": "Convert Audio to Text", "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nTranscribes an uploaded audio file to text using the workspace's default speech-to-text model.", "operationId": "audioToText", "tags": [ "Audio" ], "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": "- `no_audio_uploaded` : No audio file was provided in the `file` field.\n- `speech_to_text_disabled` : Speech-to-text is disabled for this app.\n- `provider_not_support_speech_to_text` : The model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials are configured.\n- `completion_request_error` : The speech recognition request failed.", "content": { "application/json": { "examples": { "no_audio_uploaded": { "summary": "no_audio_uploaded", "value": { "status": 400, "code": "no_audio_uploaded", "message": "Please upload your audio." } }, "speech_to_text_disabled": { "summary": "speech_to_text_disabled", "value": { "status": 400, "code": "speech_to_text_disabled", "message": "Speech to text is disabled." } }, "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." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "413": { "description": "`audio_too_large` : The audio file exceeds the `30 MB` size limit.", "content": { "application/json": { "examples": { "audio_too_large": { "summary": "audio_too_large", "value": { "status": 413, "code": "audio_too_large", "message": "Audio size larger than 30 mb" } } } } } }, "415": { "description": "`unsupported_audio_type` : The file's MIME type is not one of the accepted audio types (see the `file` field).", "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": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "x-mint": { "href": "/en/api-reference/audio/convert-audio-to-text", "metadata": { "title": "Convert Audio to Text", "sidebarTitle": "Convert Audio to Text" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/audio-to-text' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@meeting-question.mp3' \\\n --form 'user={user}'" } ] } }, "/text-to-audio": { "post": { "summary": "Convert Text to Audio", "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nConverts text to speech audio. Pass `text` to synthesize arbitrary text, or `message_id` to voice an existing message's answer.", "operationId": "textToAudioChat", "tags": [ "Audio" ], "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. The `Content-Type` header reflects the provider's audio container, verified from the response bytes when recognizable.\n\nThe body can be AAC, FLAC, MP4, MP3, Ogg, WAV, or WebM. Output that cannot be recognized is labeled with the provider's declared type, or `audio/mpeg` when none is declared.\n\nStreamed provider output is delivered with chunked transfer encoding; the request `streaming` field does not control this.", "content": { "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "audio/mp4": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/ogg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/webm": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "- `app_unavailable` : The app is unavailable or misconfigured.\n- `invalid_param` : Text-to-speech is not enabled, `text` is missing, or no voice is available.\n- `provider_not_initialize` : No valid model provider credentials are configured.\n- `provider_quota_exceeded` : The model provider quota is exhausted.\n- `model_currently_not_support` : The current model does not support this operation.\n- `completion_request_error` : The 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." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "TTS is not enabled" } }, "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": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "x-mint": { "href": "/en/api-reference/audio/convert-text-to-audio", "metadata": { "title": "Convert Text to Audio", "sidebarTitle": "Convert Text to Audio" } } } }, "/info": { "get": { "summary": "Get App Info", "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns basic information about the app: name, description, tags, mode, and author.", "operationId": "getChatAppInfo", "tags": [ "Applications" ], "responses": { "200": { "description": "Basic information of the application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponse" }, "examples": { "appInfo": { "summary": "Response Example", "value": { "name": "My Chat App", "description": "A helpful customer service chatbot.", "tags": [ "customer-service", "chatbot" ], "mode": "chat", "author_name": "Dify Team" } } } } } } }, "x-mint": { "href": "/en/api-reference/applications/get-app-info", "metadata": { "title": "Get App Info", "sidebarTitle": "Get App Info" } } } }, "/parameters": { "get": { "summary": "Get App Parameters", "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns the app's front-end configuration: the opening statement and suggested questions, feature toggles, the user input form, and file-upload limits. Use it to render the app's inputs and apply the correct upload limits.", "operationId": "getChatAppParameters", "tags": [ "Applications" ], "responses": { "200": { "description": "Application parameters information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppParametersResponse" }, "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` : The app is unavailable or misconfigured.\n- `agent_not_published` : The app's Agent has no published version yet. (Agent apps)", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "agent_not_published": { "summary": "agent_not_published", "value": { "code": "agent_not_published", "message": "Agent has not been published. Please publish the Agent before using the API.", "status": 400 } } } } } } }, "x-mint": { "href": "/en/api-reference/applications/get-app-parameters", "metadata": { "title": "Get App Parameters", "sidebarTitle": "Get App Parameters" } } } }, "/meta": { "get": { "summary": "Get App Meta", "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns the display icons for the tools this app uses, keyed by tool name.", "operationId": "getChatAppMeta", "tags": [ "Applications" ], "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": "🧮" } } } } } } } } }, "x-mint": { "href": "/en/api-reference/applications/get-app-meta", "metadata": { "title": "Get App Meta", "sidebarTitle": "Get App Meta" } } } }, "/site": { "get": { "summary": "Get App WebApp Settings", "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns the branding and display settings for the app's hosted web app, such as its title, icon, theme colors, and default language.", "operationId": "getChatWebAppSettings", "tags": [ "Applications" ], "responses": { "200": { "description": "Web app 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", "input_placeholder": "Ask me anything about our products...", "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": "You don't have the permission to access the requested resource. It is either read-protected or not readable by the server." } } } } } } }, "x-mint": { "href": "/en/api-reference/applications/get-app-webapp-settings", "metadata": { "title": "Get App WebApp Settings", "sidebarTitle": "Get App WebApp Settings" } } } }, "/apps/annotations": { "post": { "summary": "Create Annotation", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nCreates an annotation. Annotations are predefined question-answer pairs the app returns directly on a match, instead of generating a fresh response.", "operationId": "createAnnotation", "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 } } } } } } }, "x-mint": { "href": "/en/api-reference/annotations/create-annotation", "metadata": { "title": "Create Annotation", "sidebarTitle": "Create Annotation" } } }, "get": { "summary": "List Annotations", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nLists the app's annotations, optionally filtered by keyword.", "operationId": "getAnnotationList", "tags": [ "Annotations" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Number of items per page. Requests above 100 are capped at 100.", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1 } }, { "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 } } } } } } }, "x-mint": { "href": "/en/api-reference/annotations/list-annotations", "metadata": { "title": "List Annotations", "sidebarTitle": "List Annotations" } } } }, "/apps/annotations/{annotation_id}": { "put": { "summary": "Update Annotation", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nUpdates an annotation's question and answer.", "operationId": "updateAnnotation", "tags": [ "Annotations" ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "description": "ID of the annotation to update. Get annotation IDs from [List Annotations](/en/api-reference/annotations/list-annotations).", "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" } } } } } } }, "x-mint": { "href": "/en/api-reference/annotations/update-annotation", "metadata": { "title": "Update Annotation", "sidebarTitle": "Update Annotation" } } }, "delete": { "summary": "Delete Annotation", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nDeletes an annotation and its associated hit history.", "operationId": "deleteAnnotation", "tags": [ "Annotations" ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "description": "ID of the annotation to delete. Get annotation IDs from [List Annotations](/en/api-reference/annotations/list-annotations).", "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" } } } } } } }, "x-mint": { "href": "/en/api-reference/annotations/delete-annotation", "metadata": { "title": "Delete Annotation", "sidebarTitle": "Delete Annotation" } } } }, "/apps/annotation-reply/{action}": { "post": { "summary": "Configure Annotation Reply", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nEnables or disables annotation reply for the app. Runs asynchronously; track progress with [Get Annotation Reply Job Status](/en/api-reference/annotations/get-annotation-reply-job-status).\n\nThe body is validated before the action runs, so `score_threshold`, `embedding_provider_name`, and `embedding_model_name` are required even for `disable`.", "operationId": "initialAnnotationReplySettings", "tags": [ "Annotations" ], "parameters": [ { "name": "action", "in": "path", "required": true, "description": "Whether to enable or disable annotation reply.", "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" } } } } } } }, "x-mint": { "href": "/en/api-reference/annotations/configure-annotation-reply", "metadata": { "title": "Configure Annotation Reply", "sidebarTitle": "Configure Annotation Reply" } } } }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { "summary": "Get Annotation Reply Job Status", "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nReturns the status of an annotation reply configuration job started by [Configure Annotation Reply](/en/api-reference/annotations/configure-annotation-reply).", "operationId": "getInitialAnnotationReplySettingsStatus", "tags": [ "Annotations" ], "parameters": [ { "name": "action", "in": "path", "required": true, "description": "Action type, must match the [Configure Annotation Reply](/en/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](/en/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." } } } } } } }, "x-mint": { "href": "/en/api-reference/annotations/get-annotation-reply-job-status", "metadata": { "title": "Get Annotation Reply Job Status", "sidebarTitle": "Get Annotation Reply Job Status" } } } }, "/workflows/run/{workflow_run_id}": { "get": { "summary": "Get Workflow Run Detail", "description": "**Available for**: Chatflow, Workflow apps.\n\nGet a single workflow run's status, inputs, outputs, and execution metrics.", "operationId": "getWorkflowRunDetail", "tags": [ "Workflow Runs" ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "description": "Workflow run ID, from the response or streaming events of [Run Workflow](/en/api-reference/workflow-runs/run-workflow), or from message metadata in Chatflow apps.", "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/workflow-runs/get-workflow-run-detail", "metadata": { "title": "Get Workflow Run Detail", "sidebarTitle": "Get Workflow Run Detail" } } } }, "/workflows/logs": { "get": { "summary": "List Workflow Logs", "description": "**Available for**: Chatflow, Workflow apps.\n\nList past workflow runs with optional filters. Each entry is a run-level summary (status, token usage, step count, and timing), not a node-by-node execution log.\n\nTo follow a run's node-level events, stream it instead:\n\n- **A run you start**: use [Run Workflow](/en/api-reference/workflow-runs/run-workflow) in streaming mode, which emits `node_started` and `node_finished` as the run executes.\n- **A run already in progress**: call [Stream Workflow Events](/en/api-reference/workflow-runs/stream-workflow-events) with `include_state_snapshot=true` to replay each executed node's status, then stream the rest.\n\nA finished run's node-level logs aren't available through the Service API.", "operationId": "getWorkflowLogs", "tags": [ "Workflow Runs" ], "parameters": [ { "name": "keyword", "in": "query", "description": "Keyword to search in logs.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by execution status.", "schema": { "type": "string", "enum": [ "succeeded", "failed", "stopped" ] } }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 99999 } }, { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "created_at__before", "in": "query", "description": "Filter logs created before this ISO 8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at__after", "in": "query", "description": "Filter logs created after this ISO 8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_by_end_user_session_id", "in": "query", "description": "Filter by end user session ID.", "schema": { "type": "string" } }, { "name": "created_by_account", "in": "query", "description": "Filter by the creator's account email (e.g., `name@example.com`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved workflow logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponse" }, "examples": { "workflowLogs": { "summary": "Response Example", "value": { "page": 1, "limit": 20, "total": 1, "has_more": false, "data": [ { "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", "workflow_run": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "version": "2025-01-16 12:00:00.000000", "status": "succeeded", "error": null, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630, "exceptions_count": 0, "triggered_from": "app-run" }, "created_from": "service-api", "created_by_role": "end_user", "created_by_account": null, "created_by_end_user": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "type": "service-api", "is_anonymous": false, "session_id": "user_workflow_123" }, "created_at": 1705407629 } ] } } } } } }, "400": { "description": "`invalid_param` : A query parameter is invalid, such as a `created_by_account` value matching no account, a malformed `created_at__before` or `created_at__after` timestamp, or an out-of-range `page`, `limit`, or `status` value.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Account not found: name@example.com" } } } } } } }, "x-mint": { "href": "/en/api-reference/workflow-runs/list-workflow-logs", "metadata": { "title": "List Workflow Logs", "sidebarTitle": "List Workflow Logs" } } } }, "/form/human_input/{form_token}": { "get": { "tags": [ "Human Input" ], "summary": "Get Human Input Form", "description": "**Available for**: Chatflow, Workflow apps.\n\nReturns the contents of a paused Human Input form. Requires web app delivery.\n\nFor the full sequence of Human Input calls, see [Human Input Flow](/en/api-reference/guides/human-input-flow).", "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. absent 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](/en/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" } } } } } } }, "x-mint": { "href": "/en/api-reference/human-input/get-human-input-form", "metadata": { "title": "Get Human Input Form", "sidebarTitle": "Get Human Input Form" } } }, "post": { "tags": [ "Human Input" ], "summary": "Submit Human Input Form", "description": "**Available for**: Chatflow, Workflow apps.\n\nSubmits the recipient's response to a paused Human Input form. On acceptance the workflow resumes; follow the resumed run via [Stream Workflow Events](/en/api-reference/workflow-runs/stream-workflow-events). Requires web app 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.\n\nA 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`. For `local_file`, `upload_file_id` is the `id` from [Upload File](/en/api-reference/files/upload-file).\n\nUse 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](/en/api-reference/human-input/get-human-input-form))." }, "user": { "type": "string", "description": "End-user identifier, defined by your app and unique within it. Service API and web app user IDs are separate, even when identical. See [End User Identity](/en/api-reference/guides/end-user-identity)." } } }, "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" } } } } } } }, "x-mint": { "href": "/en/api-reference/human-input/submit-human-input-form", "metadata": { "title": "Submit Human Input Form", "sidebarTitle": "Submit Human Input Form" } } } }, "/workflow/{workflow_run_id}/events": { "get": { "tags": [ "Workflow Runs" ], "summary": "Stream Workflow Events", "description": "**Available for**: Chatflow, Workflow apps.\n\nResume the Server-Sent Events stream for a workflow run after a pause or a dropped SSE connection. For runs that have already finished, the stream emits a single `workflow_finished` event and closes.\n\nTo check an in-progress run's node-level status and progress, call it with `include_state_snapshot=true`: the stream replays each already-executed node's status before streaming new events.", "operationId": "streamWorkflowEvents", "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workflow run ID whose event stream to resume, from the response or streaming events of [Run Workflow](/en/api-reference/workflow-runs/run-workflow)." }, { "name": "user", "in": "query", "required": true, "schema": { "type": "string" }, "description": "End-user identifier, defined by your app and unique within it. Must match the `user` that started the run. See [End User Identity](/en/api-reference/guides/end-user-identity)." }, { "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. It opens with a bare `event: ping` frame (keep-alive; more arrive roughly every 10 seconds); every other event is delivered as `data: {JSON}\\n\\n`. Event payloads follow the same schemas as the original streaming response.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE stream of events from a resumed workflow run, in the same format as [Run Workflow](/en/api-reference/workflow-runs/run-workflow) (Workflow apps) or [Send Chat Message](/en/api-reference/chat-messages/send-chat-message) (Chatflow apps). 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 (Workflow)", "value": "event: ping\n\ndata: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\", \"submitted_data\": {\"comment\": \"Looks good.\"}}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_2\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 2, \"created_at\": 1705407705}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Approved, now translating.\", \"node_id\": \"node_1\", \"is_final\": false}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}}\n\ndata: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour\"}, \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}" }, "resumedRunChatflow": { "summary": "Response Example - Resumed run (Chatflow)", "value": "event: ping\n\ndata: {\"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\", \"submitted_data\": {\"comment\": \"Looks good.\"}}}\n\ndata: {\"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}}\n\ndata: {\"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}}\n\ndata: {\"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}}\n\ndata: {\"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}\n\ndata: {\"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}}\n\ndata: {\"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}}}\n\ndata: {\"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}'" } ], "x-mint": { "href": "/en/api-reference/workflow-runs/stream-workflow-events", "metadata": { "title": "Stream Workflow Events", "sidebarTitle": "Stream Workflow Events" } } } }, "/workflows/run": { "post": { "summary": "Run Workflow", "description": "**Available for**: Workflow apps.\n\nRun the app's published workflow and return its outputs, either in a single `blocking` response or as a `streaming` Server-Sent Events feed. Requires a published workflow.", "operationId": "executeWorkflow", "tags": [ "Workflow Runs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { "streaming_example": { "summary": "Request Example - Streaming mode", "value": { "inputs": { "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", "user": "user_workflow_123" } }, "blocking_example": { "summary": "Request Example - Blocking mode", "value": { "inputs": { "query": "Translate this to French: Hello world" }, "response_mode": "blocking", "user": "user_workflow_456" } }, "with_file_array_variable": { "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", "transfer_method": "remote_url", "url": "https://example.com/image.jpg" } ] }, "response_mode": "blocking", "user": "user_workflow_789" } } } } } }, "responses": { "200": { "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" }, "examples": { "blockingResponse": { "summary": "Response Example - Blocking mode", "value": { "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": { "result": "Bonjour le monde" }, "error": null, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630 } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive; the stream opens with one, then more arrive roughly every 10 seconds).\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries `message_id: null` and no `conversation_id`. The parallel `text_chunk` stream stays free of `` tags.\n\n**Human Input events**:\n- `human_input_required`: Fires together with `workflow_paused` when the workflow reaches a Human Input node. Use the `form_token` from the payload to drive the form-handling flow via the [Human Input API](/en/api-reference/human-input/get-human-input-form).\n- `human_input_form_filled`: A recipient submitted the form; workflow execution resumes.\n- `human_input_form_timeout`: The form expired without a response. Workflow follows the timeout fallback edge if defined." }, "examples": { "streamingResponse": { "summary": "Response Example - Streaming mode", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}}\n\ndata: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" }, "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}}\n\ndata: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}}\n\ndata: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : A request parameter is missing or invalid, such as a missing `user` or an unpublished workflow.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "429": { "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached.", "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/workflow-runs/run-workflow", "metadata": { "title": "Run Workflow", "sidebarTitle": "Run Workflow" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -N --request POST \\\n --url 'https://{api_base_url}/workflows/run' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --data '{\"inputs\": {\"query\": \"Summarize this text: The quick brown fox jumps over the lazy dog.\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'" } ] } }, "/workflows/{workflow_id}/run": { "post": { "summary": "Run Workflow by ID", "description": "**Available for**: Workflow apps.\n\nRun a specific published workflow version, identified by the `workflow_id` in the path. Request body, response, and streaming behavior match [Run Workflow](/en/api-reference/workflow-runs/run-workflow); only the executed version differs.", "operationId": "runWorkflowById", "tags": [ "Workflow Runs" ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "description": "Published workflow version to run. Returned in the `workflow_id` field of [Run Workflow](/en/api-reference/workflow-runs/run-workflow) responses and [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail). Must reference a published version; a draft version ID is rejected with `bad_request`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { "example": { "summary": "Request Example", "value": { "inputs": { "query": "Summarize this article" }, "response_mode": "blocking", "user": "user_workflow_123" } } } } } }, "responses": { "200": { "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" }, "examples": { "blockingResponse": { "summary": "Response Example - Blocking mode", "value": { "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": { "result": "Article summary here" }, "error": null, "elapsed_time": 2.45, "total_tokens": 280, "total_steps": 4, "created_at": 1705407629, "finished_at": 1705407631 } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive; the stream opens with one, then more arrive roughly every 10 seconds).\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries `message_id: null` and no `conversation_id`. The parallel `text_chunk` stream stays free of `` tags.\n\n**Human Input events**:\n- `human_input_required`: Fires together with `workflow_paused` when the workflow reaches a Human Input node. Use the `form_token` from the payload to drive the form-handling flow via the [Human Input API](/en/api-reference/human-input/get-human-input-form).\n- `human_input_form_filled`: A recipient submitted the form; workflow execution resumes.\n- `human_input_form_timeout`: The form expired without a response. Workflow follows the timeout fallback edge if defined." }, "examples": { "streamingResponse": { "summary": "Response Example - Streaming mode", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}}\n\ndata: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" }, "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}}\n\ndata: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}}\n\ndata: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : A request parameter is missing or invalid, such as a missing `user`.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Cannot use draft workflow version. Workflow ID: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345. Please use a published workflow version or leave workflow_id empty." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "403": { "description": "`workflow_version_execution_not_allowed` : Executing a specific workflow version is not available on the Dify Cloud Sandbox plan.", "content": { "application/json": { "examples": { "workflow_version_execution_not_allowed": { "summary": "workflow_version_execution_not_allowed", "value": { "status": 403, "code": "workflow_version_execution_not_allowed", "message": "Workflow version execution is not available on your current plan. Please upgrade to a paid plan." } } } } } }, "404": { "description": "`not_found` : Workflow not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow not found with id: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345" } } } } } }, "429": { "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached.", "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." } } } } } } }, "x-mint": { "href": "/en/api-reference/workflow-runs/run-workflow-by-id", "metadata": { "title": "Run Workflow by ID", "sidebarTitle": "Run Workflow by ID" } } } }, "/workflows/tasks/{task_id}/stop": { "post": { "summary": "Stop Workflow Task", "description": "**Available for**: Workflow apps.\n\nStop a running workflow task. Only supported in `streaming` mode.", "operationId": "stopWorkflowTaskGeneration", "tags": [ "Workflow Runs" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "Task ID, from the streaming events of [Run Workflow](/en/api-reference/workflow-runs/run-workflow).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "End-user identifier, defined by your app and unique within it. Need not match the `user` that started the run; the stop applies to the task regardless of `user`. See [End User Identity](/en/api-reference/guides/end-user-identity)." } } }, "examples": { "example": { "summary": "Request Example", "value": { "user": "user_workflow_123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `invalid_param` : A request parameter is missing or invalid, such as a missing `user`.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } } }, "x-mint": { "href": "/en/api-reference/workflow-runs/stop-workflow-task", "metadata": { "title": "Stop Workflow Task", "sidebarTitle": "Stop Workflow Task" } } } }, "/completion-messages": { "post": { "summary": "Send Completion Message", "description": "**Available for**: Text Generator apps.\n\nSends a request to a text-generation app and returns the generated text.", "operationId": "createCompletionMessage", "tags": [ "Completion Messages" ], "requestBody": { "description": "Request body to create a completion message.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionRequest" }, "examples": { "streaming_example": { "summary": "Request Example - Streaming mode", "value": { "inputs": { "city": "San Francisco" }, "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", "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": { "city": "New York" }, "query": "Summarize the following text: ...", "response_mode": "blocking", "user": "def-456" } } } } } }, "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 `CompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkCompletionEvent` objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionResponse" }, "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", "mode": "completion", "answer": "Hello World!...", "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 } }, "created_at": 1705407629 } } } }, "text/event-stream": { "schema": { "type": "string", "description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive every 10 seconds). See `ChunkCompletionEvent` for the event structures.\n\n**Stream lifecycle**: the reply streams as `message` chunks and ends with `message_end`. An `error` event ends the stream early; HTTP status stays `200`, so inspect the event payload for details." }, "examples": { "streamingResponse": { "summary": "Response Example - Streaming mode", "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n" } } } } }, "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 unavailable.\n- `completion_request_error` : Text generation failed.\n- `invalid_param` : The required `user` field is missing.", "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." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "429": { "description": "`too_many_requests` : Too many concurrent requests for this app.", "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. The current maximum concurrent requests allowed for 5b3d4f2a-1c9e-4a7b-8f6d-2e0c9a1b3d4f is 10." } } } } } }, "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": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "x-mint": { "href": "/en/api-reference/completion-messages/send-completion-message", "metadata": { "title": "Send Completion Message", "sidebarTitle": "Send Completion Message" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/completion-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"inputs\": {\"city\": \"San Francisco\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'" } ] } }, "/completion-messages/{task_id}/stop": { "post": { "summary": "Stop Completion Message Generation", "description": "**Available for**: Text Generator apps.\n\nStops a completion message generation task. Only supported in `streaming` mode.", "operationId": "stopGenerate", "tags": [ "Completion Messages" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "Task ID, from the streaming events of [Send Completion Message](/en/api-reference/completion-messages/send-completion-message).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "End-user identifier, defined by your app and unique within it. Must match the `user` sent with the original message; if it differs, the stop silently does nothing and still returns success. See [End User Identity](/en/api-reference/guides/end-user-identity)." } } }, "examples": { "example": { "summary": "Request Example", "value": { "user": "abc-123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `invalid_param` : The required `user` field is missing.", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } } }, "x-mint": { "href": "/en/api-reference/completion-messages/stop-completion-message-generation", "metadata": { "title": "Stop Completion Message Generation", "sidebarTitle": "Stop Completion Message Generation" } } } }, "/datasets": { "post": { "tags": [ "Knowledge Bases" ], "summary": "Create an Empty Knowledge Base", "description": "Creates an empty knowledge base. Add documents to it with [Create Document by Text](/en/api-reference/documents/create-document-by-text) or [Create Document by File](/en/api-reference/documents/create-document-by-file).", "operationId": "createDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Name of the knowledge base." }, "description": { "type": "string", "maxLength": 400, "default": "", "description": "Description of the knowledge base." }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ], "nullable": true, "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." }, "permission": { "type": "string", "enum": [ "only_me", "all_team_members", "partial_members" ], "default": "only_me", "description": "Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members." }, "provider": { "type": "string", "enum": [ "vendor", "external" ], "default": "vendor", "description": "`vendor` for internal knowledge base, `external` for external knowledge base." }, "embedding_model": { "type": "string", "description": "Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`." }, "embedding_model_provider": { "type": "string", "description": "Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius//` and works only for langgenius-published plugins.\n\nGet valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`." }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." }, "external_knowledge_api_id": { "type": "string", "description": "ID of the external knowledge API connection." }, "external_knowledge_id": { "type": "string", "description": "ID of the external knowledge base." }, "summary_index_setting": { "type": "object", "nullable": true, "description": "Summary index configuration.", "properties": { "enable": { "type": "boolean", "description": "Whether to enable summary indexing." }, "model_name": { "type": "string", "description": "Name of the model used for generating summaries." }, "model_provider_name": { "type": "string", "description": "Provider of the summary generation model." }, "summary_prompt": { "type": "string", "description": "Custom prompt template for summary generation." } } } } } } } }, "responses": { "200": { "description": "Knowledge base created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" }, "examples": { "success": { "summary": "Response Example", "value": { "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "name": "Product Documentation", "description": "Technical documentation for the product API", "provider": "vendor", "permission": "only_me", "data_source_type": null, "indexing_technique": "high_quality", "app_count": 0, "document_count": 0, "word_count": 0, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "author_name": "admin", "created_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "updated_at": 1741267200, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "embedding_available": true, "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "", "reranking_model_name": "" }, "weights": null, "top_k": 3, "score_threshold_enabled": false, "score_threshold": null }, "tags": [], "doc_form": "text_model", "external_knowledge_info": null, "external_retrieval_model": null, "doc_metadata": [], "built_in_field_enabled": true, "pipeline_id": null, "runtime_mode": null, "chunk_structure": null, "icon_info": null, "summary_index_setting": null, "is_published": false, "total_documents": 0, "total_available_documents": 0, "enable_api": true, "is_multimodal": false, "maintainer": "admin" } } } } } }, "400": { "description": "`invalid_param` : The embedding or reranking model you specified is not configured or available.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } } } } } }, "403": { "description": "`forbidden` : Your subscription's knowledge base request rate limit has been reached.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "409": { "description": "`dataset_name_duplicate` : A knowledge base with the same name already exists.", "content": { "application/json": { "examples": { "dataset_name_duplicate": { "summary": "dataset_name_duplicate", "value": { "status": 409, "code": "dataset_name_duplicate", "message": "The dataset name already exists. Please modify your dataset name." } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-bases/create-an-empty-knowledge-base", "metadata": { "title": "Create an Empty Knowledge Base", "sidebarTitle": "Create an Empty Knowledge Base" } } }, "get": { "tags": [ "Knowledge Bases" ], "summary": "List Knowledge Bases", "description": "Returns a paginated list of knowledge bases, optionally filtered by keyword or tags.", "operationId": "listDatasets", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 }, "description": "Number of items per page." }, { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Search keyword to filter by name." }, { "name": "include_all", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Whether to include all knowledge bases regardless of permissions." }, { "name": "tag_ids", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Tag IDs to filter by. Get tag IDs from [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags)." } ], "responses": { "200": { "description": "List of knowledge bases.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of knowledge base objects.", "items": { "$ref": "#/components/schemas/Dataset" } }, "has_more": { "type": "boolean", "description": "Whether more items exist on the next page." }, "limit": { "type": "integer", "description": "Number of items per page." }, "total": { "type": "integer", "description": "Total number of matching items." }, "page": { "type": "integer", "description": "Current page number." } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "name": "Product Documentation", "description": "Technical documentation for the product API", "provider": "vendor", "permission": "only_me", "data_source_type": null, "indexing_technique": "high_quality", "app_count": 0, "document_count": 0, "word_count": 0, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "author_name": "admin", "created_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "updated_at": 1741267200, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "embedding_available": true, "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "", "reranking_model_name": "" }, "weights": null, "top_k": 3, "score_threshold_enabled": false, "score_threshold": null }, "tags": [], "doc_form": "text_model", "external_knowledge_info": null, "external_retrieval_model": null, "doc_metadata": [], "built_in_field_enabled": true, "pipeline_id": null, "runtime_mode": null, "chunk_structure": null, "icon_info": null, "summary_index_setting": null, "is_published": false, "total_documents": 0, "total_available_documents": 0, "enable_api": true, "is_multimodal": false, "maintainer": "admin" } ], "has_more": false, "limit": 20, "total": 1, "page": 1 } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-bases/list-knowledge-bases", "metadata": { "title": "List Knowledge Bases", "sidebarTitle": "List Knowledge Bases" } } } }, "/datasets/{dataset_id}": { "get": { "tags": [ "Knowledge Bases" ], "summary": "Get Knowledge Base", "description": "Returns detailed information about a knowledge base, including its embedding model, retrieval configuration, and document statistics.", "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "responses": { "200": { "description": "Knowledge base details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" }, "examples": { "success": { "summary": "Response Example", "value": { "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "name": "Product Documentation", "description": "Technical documentation for the product API", "provider": "vendor", "permission": "only_me", "data_source_type": null, "indexing_technique": "high_quality", "app_count": 0, "document_count": 0, "word_count": 0, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "author_name": "admin", "created_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "updated_at": 1741267200, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "embedding_available": true, "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "", "reranking_model_name": "" }, "weights": null, "top_k": 3, "score_threshold_enabled": false, "score_threshold": null }, "tags": [], "doc_form": "text_model", "external_knowledge_info": null, "external_retrieval_model": null, "doc_metadata": [], "built_in_field_enabled": true, "pipeline_id": null, "runtime_mode": null, "chunk_structure": null, "icon_info": null, "summary_index_setting": null, "is_published": false, "total_documents": 0, "total_available_documents": 0, "enable_api": true, "is_multimodal": false, "maintainer": "admin" } } } } } }, "403": { "description": "`forbidden` : API access is not enabled for this knowledge base.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : No knowledge base matches `dataset_id`.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-bases/get-knowledge-base", "metadata": { "title": "Get Knowledge Base", "sidebarTitle": "Get Knowledge Base" } } }, "patch": { "tags": [ "Knowledge Bases" ], "summary": "Update Knowledge Base", "description": "Updates a knowledge base. Only the fields included in the request body are changed.", "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Name of the knowledge base." }, "description": { "type": "string", "maxLength": 400, "description": "Description of the knowledge base." }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ], "nullable": true, "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." }, "permission": { "type": "string", "enum": [ "only_me", "all_team_members", "partial_members" ], "description": "Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members." }, "embedding_model": { "type": "string", "description": "Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`." }, "embedding_model_provider": { "type": "string", "description": "Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius//` and works only for langgenius-published plugins.\n\nGet valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`." }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." }, "partial_member_list": { "type": "array", "description": "List of team members with access when `permission` is `partial_members`.", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "ID of the team member to grant access." } } } }, "external_retrieval_model": { "type": "object", "description": "Retrieval settings for external knowledge bases.", "properties": { "top_k": { "type": "integer", "description": "Maximum number of results to return." }, "score_threshold": { "type": "number", "description": "Minimum similarity score threshold for filtering results." }, "score_threshold_enabled": { "type": "boolean", "description": "Whether score threshold filtering is enabled." } } }, "external_knowledge_id": { "type": "string", "description": "ID of the external knowledge base." }, "external_knowledge_api_id": { "type": "string", "description": "ID of the external knowledge API connection." } } } } } }, "responses": { "200": { "description": "Knowledge base updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" }, "examples": { "success": { "summary": "Response Example", "value": { "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "name": "Product Documentation", "description": "Technical documentation for the product API", "provider": "vendor", "permission": "only_me", "data_source_type": null, "indexing_technique": "high_quality", "app_count": 0, "document_count": 0, "word_count": 0, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "author_name": "admin", "created_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "updated_at": 1741267200, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "embedding_available": true, "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "", "reranking_model_name": "" }, "weights": null, "top_k": 3, "score_threshold_enabled": false, "score_threshold": null }, "tags": [], "doc_form": "text_model", "external_knowledge_info": null, "external_retrieval_model": null, "doc_metadata": [], "built_in_field_enabled": true, "pipeline_id": null, "runtime_mode": null, "chunk_structure": null, "icon_info": null, "summary_index_setting": null, "is_published": false, "total_documents": 0, "total_available_documents": 0, "enable_api": true, "is_multimodal": false, "maintainer": "admin", "partial_member_list": [] } } } } } }, "400": { "description": "`invalid_param` : The embedding or reranking model you specified is not configured or available.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } } } } } }, "403": { "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : Your subscription's knowledge base request rate limit has been reached.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : No knowledge base matches `dataset_id`.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-bases/update-knowledge-base", "metadata": { "title": "Update Knowledge Base", "sidebarTitle": "Update Knowledge Base" } } }, "delete": { "tags": [ "Knowledge Bases" ], "summary": "Delete Knowledge Base", "description": "Permanently deletes a knowledge base and all of its documents.", "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "responses": { "204": { "description": "Knowledge base deleted successfully." }, "403": { "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : Your subscription's knowledge base request rate limit has been reached.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : No knowledge base matches `dataset_id`.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-bases/delete-knowledge-base", "metadata": { "title": "Delete Knowledge Base", "sidebarTitle": "Delete Knowledge Base" } } } }, "/datasets/{dataset_id}/document/create-by-text": { "post": { "tags": [ "Documents" ], "summary": "Create Document by Text", "description": "Creates a document in a knowledge base from raw text. Indexing runs asynchronously; track it with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).", "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "text" ], "properties": { "name": { "type": "string", "description": "Document name." }, "text": { "type": "string", "description": "Document text content." }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ], "description": "Required when adding the first document to a knowledge base. Subsequent documents inherit the knowledge base's indexing technique if omitted. `high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." }, "doc_form": { "type": "string", "enum": [ "text_model", "hierarchical_model", "qa_model" ], "default": "text_model", "description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction." }, "doc_language": { "type": "string", "default": "English", "description": "Language of the document for processing optimization." }, "process_rule": { "type": "object", "description": "Processing rules for chunking.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "automatic", "custom", "hierarchical" ], "description": "`automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`)." }, "rules": { "type": "object", "properties": { "pre_processing_rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "remove_stopwords", "remove_extra_spaces", "remove_urls_emails" ], "description": "Rule identifier." }, "enabled": { "type": "boolean", "description": "Whether this preprocessing rule is enabled." } } } }, "segmentation": { "type": "object", "properties": { "separator": { "type": "string", "default": "\n", "description": "Custom separator for splitting text." }, "max_tokens": { "type": "integer", "description": "Maximum token count per chunk." }, "chunk_overlap": { "type": "integer", "default": 0, "description": "Token overlap between chunks." } } } } } } }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Controls how chunks are searched and ranked when querying this knowledge base." }, "embedding_model": { "type": "string", "description": "Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`." }, "embedding_model_provider": { "type": "string", "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`." }, "original_document_id": { "type": "string", "description": "Original document ID for versioning. Get it from [List Documents](/en/api-reference/documents/list-documents)." } } } } } }, "responses": { "200": { "description": "Document created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "Batch ID for tracking indexing progress." } } }, "examples": { "success": { "summary": "Response Example", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 0, "indexing_status": "indexing", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "indexing", "word_count": 0, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "400": { "description": "- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : `indexing_technique` is required when adding the first document, or `doc_form` is invalid.", "content": { "application/json": { "examples": { "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." } }, "invalid_param_indexing": { "summary": "invalid_param (indexing_technique)", "value": { "status": 400, "code": "invalid_param", "message": "indexing_technique is required." } } } } } }, "403": { "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : The number of documents has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (documents limit)", "value": { "status": 403, "code": "forbidden", "message": "The number of documents has reached the limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : Knowledge base not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } }, "503": { "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "status": 503, "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/create-document-by-text", "metadata": { "title": "Create Document by Text", "sidebarTitle": "Create Document by Text" } } } }, "/datasets/{dataset_id}/document/create-by-file": { "post": { "tags": [ "Documents" ], "summary": "Create Document by File", "description": "Creates a document in a knowledge base from an uploaded file. Common formats such as PDF, TXT, and DOCX are supported. Indexing runs asynchronously; track it with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).", "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload, capped at 15 MB by default.\n\nSelf-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments). On Dify Cloud, Professional and Team plans raise the cap to 50 MB." }, "data": { "type": "string", "description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`indexing_technique`, `doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.", "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } } } }, "responses": { "200": { "description": "Document created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "Batch ID for tracking indexing progress." } } }, "examples": { "success": { "summary": "Response Example", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 0, "indexing_status": "indexing", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "indexing", "word_count": 0, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "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- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : The knowledge base is external, `indexing_technique` is required, or `process_rule` is missing.", "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." } }, "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." } }, "invalid_param_external": { "summary": "invalid_param (external)", "value": { "status": 400, "code": "invalid_param", "message": "External datasets are not supported." } } } } } }, "403": { "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : The number of documents has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (documents limit)", "value": { "status": 403, "code": "forbidden", "message": "The number of documents has reached the limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : Knowledge base not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } }, "413": { "description": "`file_too_large` : The uploaded file exceeds the maximum size.", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "File size exceeded." } } } } } }, "503": { "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "status": 503, "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/create-document-by-file", "metadata": { "title": "Create Document by File", "sidebarTitle": "Create Document by File" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/document/create-by-file' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'" } ] } }, "/datasets/{dataset_id}/documents": { "get": { "tags": [ "Documents" ], "summary": "List Documents", "description": "Returns a paginated list of documents in a knowledge base.", "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 }, "description": "Number of items per page. Server caps at `100`." }, { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Search keyword to filter by document name." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queuing", "indexing", "paused", "error", "available", "disabled", "archived" ] }, "description": "Filter by display status." } ], "responses": { "200": { "description": "List of documents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of document objects.", "items": { "$ref": "#/components/schemas/Document" } }, "has_more": { "type": "boolean", "description": "Whether more items exist on the next page." }, "limit": { "type": "integer", "description": "Number of items per page." }, "total": { "type": "integer", "description": "Total number of matching items." }, "page": { "type": "integer", "description": "Current page number." } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "word_count": 350, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false } ], "has_more": false, "limit": 20, "total": 1, "page": 1 } } } } } }, "403": { "description": "`forbidden` : Knowledge base API access is not enabled.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : Knowledge base not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/list-documents", "metadata": { "title": "List Documents", "sidebarTitle": "List Documents" } } } }, "/datasets/{dataset_id}/documents/{document_id}": { "get": { "tags": [ "Documents" ], "summary": "Get Document", "description": "Returns detailed information for a single document.", "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)." }, { "name": "metadata", "in": "query", "schema": { "type": "string", "enum": [ "all", "only", "without" ], "default": "all" }, "description": "`all` returns all fields including metadata. `only` returns only `id`, `doc_type`, and `doc_metadata`. `without` returns all fields except `doc_metadata`." } ], "responses": { "200": { "description": "Document details. The returned fields depend on the `metadata` query parameter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Document identifier." }, "position": { "type": "integer", "description": "Position index within the knowledge base." }, "data_source_type": { "type": "string", "description": "How the document was uploaded. `upload_file` for file uploads, `notion_import` for Notion imports." }, "data_source_info": { "type": "object", "description": "Data source details. For file uploads, this detail endpoint returns the full file object under `upload_file` (the list endpoint returns only `upload_file_id`).", "properties": { "upload_file": { "type": "object", "description": "Uploaded file details. Present when `data_source_type` is `upload_file`.", "properties": { "id": { "type": "string", "description": "File identifier." }, "name": { "type": "string", "description": "Original file name." }, "size": { "type": "integer", "description": "File size in bytes." }, "extension": { "type": "string", "description": "File extension." }, "mime_type": { "type": "string", "description": "File MIME type." }, "created_by": { "type": "string", "description": "ID of the user who uploaded the file." }, "created_at": { "type": "integer", "description": "Unix timestamp of file upload." } } } } }, "dataset_process_rule_id": { "type": "string", "description": "ID of the processing rule applied to this document." }, "dataset_process_rule": { "type": "object", "description": "Knowledge-base-level processing rule configuration." }, "document_process_rule": { "type": "object", "description": "Document-level processing rule configuration." }, "name": { "type": "string", "description": "Document name." }, "created_from": { "type": "string", "description": "Origin of the document. `api` for API creation, `web` for UI creation." }, "created_by": { "type": "string", "description": "ID of the user who created the document." }, "created_at": { "type": "number", "description": "Unix timestamp of document creation." }, "tokens": { "type": "integer", "description": "Number of tokens in the document." }, "indexing_status": { "type": "string", "description": "Current indexing status, e.g. `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, `error`, `paused`." }, "error": { "type": "string", "nullable": true, "description": "Error message if indexing failed, `null` otherwise." }, "enabled": { "type": "boolean", "description": "Whether the document is enabled for retrieval." }, "disabled_at": { "type": "number", "nullable": true, "description": "Unix timestamp when the document was disabled, `null` if enabled." }, "disabled_by": { "type": "string", "nullable": true, "description": "ID of the user who disabled the document, `null` if enabled." }, "archived": { "type": "boolean", "description": "Whether the document is archived." }, "display_status": { "type": "string", "description": "Display-friendly indexing status for the UI." }, "hit_count": { "type": "integer", "description": "Number of times this document has been retrieved." }, "doc_form": { "type": "string", "description": "Document chunking mode. `text_model` for standard text, `hierarchical_model` for parent-child, `qa_model` for QA pairs." }, "doc_language": { "type": "string", "description": "Language of the document content." }, "doc_type": { "type": "string", "nullable": true, "description": "Document type classification, `null` if not set." }, "doc_metadata": { "type": "array", "description": "Custom metadata key-value pairs for this document.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Metadata field identifier." }, "name": { "type": "string", "description": "Metadata field name." }, "type": { "type": "string", "description": "Metadata field type." }, "value": { "type": "string", "description": "Metadata field value for this document." } } } }, "completed_at": { "type": "number", "nullable": true, "description": "Unix timestamp when processing completed, `null` if not yet completed." }, "updated_at": { "type": "number", "nullable": true, "description": "Unix timestamp of last update, `null` if never updated." }, "indexing_latency": { "type": "number", "nullable": true, "description": "Time taken for indexing in seconds, `null` if not completed." }, "segment_count": { "type": "integer", "description": "Number of chunks in the document." }, "average_segment_length": { "type": "number", "description": "Average character length of chunks." }, "summary_index_status": { "type": "string", "nullable": true, "description": "Status of summary indexing, `null` if summary index is not enabled." }, "need_summary": { "type": "boolean", "description": "Whether the document needs summary generation." } } }, "examples": { "success": { "summary": "Response Example", "value": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "dataset_process_rule": { "id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "mode": "custom" }, "document_process_rule": { "mode": "custom", "rules": { "pre_processing_rules": [], "segmentation": { "separator": "###", "max_tokens": 500, "chunk_overlap": 50 } } }, "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "hit_count": 0, "doc_form": "text_model", "doc_language": "English", "doc_type": null, "doc_metadata": [], "completed_at": 1741267260, "updated_at": 1741267260, "indexing_latency": 60.0, "segment_count": 5, "average_segment_length": 70.0, "summary_index_status": null, "need_summary": false } } } } } }, "400": { "description": "`invalid_metadata` : The `metadata` query parameter value is invalid (must be `all`, `only`, or `without`).", "content": { "application/json": { "examples": { "invalid_metadata": { "summary": "invalid_metadata", "value": { "status": 400, "code": "invalid_metadata", "message": "Invalid metadata value: only" } } } } } }, "403": { "description": "- `forbidden` : You do not have permission to access this document.\n- `forbidden` : Knowledge base API access is not enabled.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (no permission)", "value": { "status": 403, "code": "forbidden", "message": "No permission." } }, "forbidden_2": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : Document not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/get-document", "metadata": { "title": "Get Document", "sidebarTitle": "Get Document" } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete Document", "description": "Permanently deletes a document and all its chunks from the knowledge base.", "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)." } ], "responses": { "204": { "description": "Success." }, "403": { "description": "- `archived_document_immutable` : The archived document is not editable.\n- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "archived_document_immutable": { "summary": "archived_document_immutable", "value": { "status": 403, "code": "archived_document_immutable", "message": "The archived document is not editable." } }, "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : The document does not exist. Also returned as \"Dataset not found.\" when the knowledge base itself does not exist.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document Not Exists." } }, "not_found_2": { "summary": "not_found_2", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/delete-document", "metadata": { "title": "Delete Document", "sidebarTitle": "Delete Document" } } }, "patch": { "tags": [ "Documents" ], "summary": "Update Document", "description": "Updates a document by uploading a new file, then re-indexes it. This is the canonical endpoint for file-based document updates. Track progress with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).", "operationId": "updateDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload, capped at 15 MB by default.\n\nSelf-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments). On Dify Cloud, Professional and Team plans raise the cap to 50 MB." }, "data": { "type": "string", "description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.", "example": "{\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } } } }, "responses": { "200": { "description": "Document updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "Batch ID for tracking indexing progress." } } }, "examples": { "success": { "summary": "Response Example", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "word_count": 350, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "400": { "description": "- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : The document is not available for update (only available documents can be updated).", "content": { "application/json": { "examples": { "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." } }, "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." } }, "invalid_param_not_available": { "summary": "invalid_param (not available)", "value": { "status": 400, "code": "invalid_param", "message": "Document is not available" } } } } } }, "403": { "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : Knowledge base not found.\n- `not_found` : Document not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } }, "413": { "description": "`file_too_large` : The uploaded file exceeds the maximum size.", "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` : The uploaded file's type is not supported.", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } }, "503": { "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "status": 503, "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/update-document", "metadata": { "title": "Update Document", "sidebarTitle": "Update Document" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request PATCH \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/documents/{document_id}' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'" } ] } }, "/datasets/{dataset_id}/documents/{document_id}/download": { "get": { "tags": [ "Documents" ], "summary": "Download Document", "description": "Returns a signed URL for downloading a document's original uploaded file.", "operationId": "downloadDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)." } ], "responses": { "200": { "description": "Download URL generated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Signed URL to download the original uploaded file." } } }, "examples": { "success": { "summary": "Response Example", "value": { "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600" } } } } } }, "403": { "description": "- `forbidden` : You do not have permission to access this document.\n- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (no permission)", "value": { "status": 403, "code": "forbidden", "message": "No permission." } }, "forbidden_2": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : Document not found. Also returned as \"Uploaded file not found.\" when the stored file is missing, and \"Document does not have an uploaded file to download.\" for non-file documents.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_2": { "summary": "not_found_2", "value": { "status": 404, "code": "not_found", "message": "Uploaded file not found." } }, "not_found_3": { "summary": "not_found_3", "value": { "status": 404, "code": "not_found", "message": "Document does not have an uploaded file to download." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/download-document", "metadata": { "title": "Download Document", "sidebarTitle": "Download Document" } } } }, "/datasets/{dataset_id}/documents/{batch}/indexing-status": { "get": { "tags": [ "Documents" ], "summary": "Get Document Indexing Status", "description": "Returns indexing progress for every document in a batch: the current stage and chunk completion counts. Poll until each `indexing_status` reaches `completed` or `error`. Status advances through `waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`.", "operationId": "getDocumentIndexingStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "batch", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch ID returned when you create or update a document." } ], "responses": { "200": { "description": "Indexing status for documents in the batch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "List of indexing status entries.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Document identifier." }, "indexing_status": { "type": "string", "description": "Current indexing status: `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, or `error`." }, "processing_started_at": { "type": "number", "nullable": true, "description": "Unix timestamp when processing started." }, "parsing_completed_at": { "type": "number", "nullable": true, "description": "Unix timestamp when parsing completed." }, "cleaning_completed_at": { "type": "number", "nullable": true, "description": "Unix timestamp when cleaning completed." }, "splitting_completed_at": { "type": "number", "nullable": true, "description": "Unix timestamp when splitting completed." }, "completed_at": { "type": "number", "nullable": true, "description": "Unix timestamp when indexing completed." }, "paused_at": { "type": "number", "nullable": true, "description": "Timestamp when indexing was paused. `null` if not paused." }, "error": { "type": "string", "nullable": true, "description": "Error message if indexing failed. `null` if no error." }, "stopped_at": { "type": "number", "nullable": true, "description": "Timestamp when indexing was stopped. `null` if not stopped." }, "completed_segments": { "type": "integer", "description": "Number of chunks that have been indexed." }, "total_segments": { "type": "integer", "description": "Total number of chunks to be indexed." } } } } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_status": "completed", "processing_started_at": 1741267200, "parsing_completed_at": 1741267200, "cleaning_completed_at": 1741267200, "splitting_completed_at": 1741267200, "completed_at": 1741267200, "paused_at": null, "error": null, "stopped_at": null, "completed_segments": 5, "total_segments": 5 } ] } } } } } }, "403": { "description": "`forbidden` : Knowledge base API access is not enabled.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "- `not_found` : Knowledge base not found.\n- `not_found` : Documents not found.", "content": { "application/json": { "examples": { "dataset_not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "documents_not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Documents not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/get-document-indexing-status", "metadata": { "title": "Get Document Indexing Status", "sidebarTitle": "Get Document Indexing Status" } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { "post": { "tags": [ "Documents" ], "summary": "Update Document by Text", "description": "Updates a document's text content, name, or processing configuration. Re-indexes the document when its text changes.", "operationId": "updateDocumentByText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Document name. Required when `text` is provided." }, "text": { "type": "string", "description": "Document text content." }, "process_rule": { "type": "object", "description": "Processing rules for chunking.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "automatic", "custom", "hierarchical" ], "description": "`automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`)." }, "rules": { "type": "object", "properties": { "pre_processing_rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "remove_stopwords", "remove_extra_spaces", "remove_urls_emails" ], "description": "Rule identifier." }, "enabled": { "type": "boolean", "description": "Whether this preprocessing rule is enabled." } } } }, "segmentation": { "type": "object", "properties": { "separator": { "type": "string", "default": "\n", "description": "Custom separator for splitting text." }, "max_tokens": { "type": "integer", "description": "Maximum token count per chunk." }, "chunk_overlap": { "type": "integer", "default": 0, "description": "Token overlap between chunks." } } } } } } }, "doc_form": { "type": "string", "enum": [ "text_model", "hierarchical_model", "qa_model" ], "default": "text_model", "description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction." }, "doc_language": { "type": "string", "default": "English", "description": "Language of the document for processing optimization." }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Controls how chunks are searched and ranked when querying this knowledge base." } } } } } }, "responses": { "200": { "description": "Document updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "Batch ID for tracking indexing progress." } } }, "examples": { "success": { "summary": "Response Example", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "word_count": 350, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "400": { "description": "- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : `name` is required when `text` is provided, or `doc_form` is invalid.\n- `invalid_param` : The document is not available for update (only available documents can be updated).", "content": { "application/json": { "examples": { "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." } }, "invalid_param_name": { "summary": "invalid_param (name required)", "value": { "status": 400, "code": "invalid_param", "message": "name is required when text is provided." } }, "invalid_param_not_available": { "summary": "invalid_param (not available)", "value": { "status": 400, "code": "invalid_param", "message": "Document is not available" } } } } } }, "403": { "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : Knowledge base not found.\n- `not_found` : Document not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } }, "503": { "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "status": 503, "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/update-document-by-text", "metadata": { "title": "Update Document by Text", "sidebarTitle": "Update Document by Text" } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { "post": { "tags": [ "Documents" ], "summary": "Update Document by File", "description": "Deprecated. Use [Update Document](/en/api-reference/documents/update-document) instead. Updates a document by uploading a new file, then re-indexes it.", "operationId": "updateDocumentByFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload, capped at 15 MB by default.\n\nSelf-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments). On Dify Cloud, Professional and Team plans raise the cap to 50 MB." }, "data": { "type": "string", "description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.", "example": "{\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } } } }, "responses": { "200": { "description": "Document updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "Batch ID for tracking indexing progress." } } }, "examples": { "success": { "summary": "Response Example", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "word_count": 350, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "400": { "description": "- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : The document is not available for update (only available documents can be updated).", "content": { "application/json": { "examples": { "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." } }, "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." } }, "invalid_param_not_available": { "summary": "invalid_param (not available)", "value": { "status": 400, "code": "invalid_param", "message": "Document is not available" } } } } } }, "403": { "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : Knowledge base not found.\n- `not_found` : Document not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } }, "413": { "description": "`file_too_large` : The uploaded file exceeds the maximum size.", "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` : The uploaded file's type is not supported.", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } }, "503": { "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "status": 503, "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later." } } } } } } }, "deprecated": true, "x-mint": { "href": "/en/api-reference/documents/update-document-by-file", "metadata": { "title": "Update Document by File", "sidebarTitle": "Update Document by File" } } } }, "/datasets/{dataset_id}/documents/download-zip": { "post": { "tags": [ "Documents" ], "summary": "Download Documents as ZIP", "description": "Downloads one or more documents as a single ZIP archive. Only documents that were uploaded as files can be included.", "operationId": "downloadDocumentsZip", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_ids" ], "properties": { "document_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "uuid" }, "description": "Document IDs to include in the archive. Get them from [List Documents](/en/api-reference/documents/list-documents)." } } } } } }, "responses": { "200": { "description": "ZIP archive containing the requested documents.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary", "description": "ZIP archive binary stream." } } } }, "403": { "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : You do not have permission to access this knowledge base.\n- `forbidden` : You do not have permission for one of the requested documents.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (dataset permission)", "value": { "status": 403, "code": "forbidden", "message": "You do not have permission to access this dataset." } }, "forbidden_4": { "summary": "forbidden (document permission)", "value": { "status": 403, "code": "forbidden", "message": "No permission." } } } } } }, "404": { "description": "- `not_found` : Document not found.\n- `not_found` : Knowledge base not found. Also returned as \"Only uploaded-file documents can be downloaded as ZIP.\" when a requested document has no uploaded file.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_3": { "summary": "not_found_3", "value": { "status": 404, "code": "not_found", "message": "Only uploaded-file documents can be downloaded as ZIP." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/download-documents-as-zip", "metadata": { "title": "Download Documents as ZIP", "sidebarTitle": "Download Documents as ZIP" } } } }, "/datasets/{dataset_id}/documents/status/{action}": { "patch": { "tags": [ "Documents" ], "summary": "Update Document Status in Batch", "description": "Enables, disables, archives, or unarchives multiple documents in one request.", "operationId": "batchUpdateDocumentStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "enable", "disable", "archive", "un_archive" ] }, "description": "`enable` activates documents for retrieval, `disable` deactivates them, `archive` moves them to the archive, `un_archive` restores them from the archive." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_ids" ], "properties": { "document_ids": { "type": "array", "items": { "type": "string" }, "description": "Document IDs to update. Get them from [List Documents](/en/api-reference/documents/list-documents)." } } } } } }, "responses": { "200": { "description": "Documents updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "Operation result." } } }, "examples": { "success": { "summary": "Response Example", "value": { "result": "success" } } } } } }, "400": { "description": "`invalid_action` : Invalid action, or a document is in a state that does not allow the action (e.g. still indexing, or not completed).", "content": { "application/json": { "examples": { "invalid_action": { "summary": "invalid_action", "value": { "status": 400, "code": "invalid_action", "message": "Invalid action." } } } } } }, "403": { "description": "`forbidden` : Knowledge base API access is not enabled.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : Knowledge base not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/update-document-status-in-batch", "metadata": { "title": "Update Document Status in Batch", "sidebarTitle": "Update Document Status in Batch" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments": { "post": { "tags": [ "Chunks" ], "summary": "Create Chunks", "description": "Create one or more chunks within a document.", "operationId": "createSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "segments" ], "properties": { "segments": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "Chunk text content.", "minLength": 1 }, "answer": { "type": "string", "description": "Answer text. Required for Q&A-mode (`qa_model`) documents." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for the chunk." }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "description": "Attachment file IDs." } }, "required": [ "content" ] }, "description": "Array of chunk objects to create.", "minItems": 1 } } } } } }, "responses": { "200": { "description": "Chunks created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "List of created chunks.", "items": { "$ref": "#/components/schemas/Segment" } }, "doc_form": { "type": "string", "description": "Document chunking mode used by this document." } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 0, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "child_chunks": [], "attachments": [], "summary": null } ], "doc_form": "text_model" } } } } } }, "400": { "description": "- `provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : A chunk field is invalid (for example, `answer` is required for Q&A-mode documents) or the number of chunks exceeds the per-request limit.\n- Request-body schema validation (such as empty `content`) returns a non-standard body `{\"error\": \"\"}` with no `code` or `status` field.", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } }, "invalid_param_limit": { "summary": "invalid_param (segments limit)", "value": { "status": 400, "code": "invalid_param", "message": "Exceeded maximum segments limit of 1000." } }, "validation_error": { "summary": "schema validation (non-standard body)", "value": { "error": "1 validation error for SegmentCreatePayload\nsegments.0.content\n String should have at least 1 character [type=string_too_short, input_value='', input_type=str]" } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (upgrade plan)", "value": { "status": 403, "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan." } } } } } }, "404": { "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Document is not completed.\n- `not_found` : Document is disabled.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document is not completed." } }, "not_found_4": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document is disabled." } } } } } }, "503": { "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "status": 503, "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later." } } } } } } }, "x-mint": { "href": "/en/api-reference/chunks/create-chunks", "metadata": { "title": "Create Chunks", "sidebarTitle": "Create Chunks" } } }, "get": { "tags": [ "Chunks" ], "summary": "List Chunks", "description": "Returns a paginated list of chunks within a document, optionally filtered by keyword or indexing status.", "operationId": "listSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1 }, "description": "Number of items per page. Server caps at `100`." }, { "name": "status", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Filter chunks by indexing status, e.g. `completed`, `indexing`, `error`." }, { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Search keyword." } ], "responses": { "200": { "description": "List of chunks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "List of chunks.", "items": { "$ref": "#/components/schemas/Segment" } }, "doc_form": { "type": "string", "description": "Document chunking mode used by this document." }, "total": { "type": "integer", "description": "Total number of matching chunks." }, "has_more": { "type": "boolean", "description": "Whether more items exist on the next page." }, "limit": { "type": "integer", "description": "Number of items per page." }, "page": { "type": "integer", "description": "Current page number." } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 0, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "child_chunks": [], "attachments": [], "summary": null } ], "doc_form": "text_model", "total": 1, "has_more": false, "limit": 20, "page": 1 } } } } } }, "400": { "description": "`provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } } } } } }, "403": { "description": "`forbidden` : Dataset api access is not enabled.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/chunks/list-chunks", "metadata": { "title": "List Chunks", "sidebarTitle": "List Chunks" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { "get": { "tags": [ "Chunks" ], "summary": "Get Chunk", "description": "Retrieve the full details of a single chunk.", "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)." } ], "responses": { "200": { "description": "Chunk details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "doc_form": { "type": "string", "description": "Document chunking mode used by this document." } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 0, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "child_chunks": [], "attachments": [], "summary": null }, "doc_form": "text_model" } } } } } }, "400": { "description": "`invalid_param` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } } } } } }, "403": { "description": "`forbidden` : Dataset api access is not enabled.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/chunks/get-chunk", "metadata": { "title": "Get Chunk", "sidebarTitle": "Get Chunk" } } }, "post": { "tags": [ "Chunks" ], "summary": "Update Chunk", "description": "Update a chunk's fields. The update re-triggers indexing for that chunk.", "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "segment" ], "properties": { "segment": { "type": "object", "properties": { "content": { "type": "string", "description": "Chunk text content." }, "answer": { "type": "string", "description": "Answer text for Q&A-mode (`qa_model`) documents." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords for the chunk." }, "enabled": { "type": "boolean", "description": "Whether the chunk is enabled." }, "regenerate_child_chunks": { "type": "boolean", "default": false, "description": "Whether to regenerate child chunks." }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "description": "Attachment file IDs." }, "summary": { "type": "string", "nullable": true, "description": "Summary content for summary index." } }, "description": "Chunk data to update." } } } } } }, "responses": { "200": { "description": "Chunk updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "doc_form": { "type": "string", "description": "Document chunking mode used by this document." } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 0, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "child_chunks": [], "attachments": [], "summary": null }, "doc_form": "text_model" } } } } } }, "400": { "description": "- `provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : The chunk is indexing or disabled and cannot be updated, or index configuration is invalid.", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } }, "invalid_param_state": { "summary": "invalid_param (state)", "value": { "status": 400, "code": "invalid_param", "message": "Segment is indexing, please try again later" } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } }, "503": { "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "status": 503, "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later." } } } } } } }, "x-mint": { "href": "/en/api-reference/chunks/update-chunk", "metadata": { "title": "Update Chunk", "sidebarTitle": "Update Chunk" } } }, "delete": { "tags": [ "Chunks" ], "summary": "Delete Chunk", "description": "Permanently delete a chunk from the document.", "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)." } ], "responses": { "204": { "description": "Success." }, "400": { "description": "- `invalid_param` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : The chunk is already being deleted by a concurrent request.", "content": { "application/json": { "examples": { "invalid_param_model_setting": { "summary": "invalid_param (model setting)", "value": { "status": 400, "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } }, "invalid_param_deleting": { "summary": "invalid_param (deleting)", "value": { "status": 400, "code": "invalid_param", "message": "Segment is deleting." } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/chunks/delete-chunk", "metadata": { "title": "Delete Chunk", "sidebarTitle": "Delete Chunk" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { "post": { "tags": [ "Chunks" ], "summary": "Create Child Chunk", "description": "Create a child chunk under a parent chunk. Intended for documents that use the parent-child (`hierarchical_model`) chunking mode.", "operationId": "createChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "Child chunk text content." } } } } } }, "responses": { "200": { "description": "Child chunk created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChildChunk" } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": { "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "content": "Dify is an open-source platform.", "position": 1, "word_count": 6, "type": "customized", "created_at": 1741267200, "updated_at": 1741267200 } } } } } } }, "400": { "description": "- `provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : Indexing the child chunk in the vector store failed; the message carries the underlying vector-store error.", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Vector store operation failed: [Errno 111] Connection refused" } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (upgrade plan)", "value": { "status": 403, "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan." } } } } } }, "404": { "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } }, "503": { "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "status": 503, "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later." } } } } } } }, "x-mint": { "href": "/en/api-reference/chunks/create-child-chunk", "metadata": { "title": "Create Child Chunk", "sidebarTitle": "Create Child Chunk" } } }, "get": { "tags": [ "Chunks" ], "summary": "List Child Chunks", "description": "Returns a paginated list of child chunks under a specific parent chunk.", "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1 }, "description": "Number of items per page. Server caps at `100`." }, { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "Search keyword." } ], "responses": { "200": { "description": "List of child chunks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "List of child chunks.", "items": { "$ref": "#/components/schemas/ChildChunk" } }, "total": { "type": "integer", "description": "Total number of child chunks." }, "total_pages": { "type": "integer", "description": "Total number of pages." }, "page": { "type": "integer", "description": "Current page number." }, "limit": { "type": "integer", "description": "Number of items per page." } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "content": "Dify is an open-source platform.", "position": 1, "word_count": 6, "type": "customized", "created_at": 1741267200, "updated_at": 1741267200 } ], "total": 1, "total_pages": 1, "page": 1, "limit": 20 } } } } } }, "403": { "description": "`forbidden` : Dataset api access is not enabled.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/chunks/list-child-chunks", "metadata": { "title": "List Child Chunks", "sidebarTitle": "List Child Chunks" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { "patch": { "tags": [ "Chunks" ], "summary": "Update Child Chunk", "description": "Update the content of an existing child chunk.", "operationId": "updateChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)." }, { "name": "child_chunk_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Child chunk ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "Child chunk text content." } } } } } }, "responses": { "200": { "description": "Child chunk updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChildChunk" } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": { "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "content": "Dify is an open-source platform.", "position": 1, "word_count": 6, "type": "customized", "created_at": 1741267200, "updated_at": 1741267200 } } } } } } }, "400": { "description": "`invalid_param` : Re-indexing the child chunk in the vector store failed; the message carries the underlying vector-store error.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Vector store operation failed: [Errno 111] Connection refused" } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (upgrade plan)", "value": { "status": 403, "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan." } } } } } }, "404": { "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.\n- `not_found` : Child chunk not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } }, "not_found_4": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Child chunk not found." } } } } } }, "503": { "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "status": 503, "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later." } } } } } } }, "x-mint": { "href": "/en/api-reference/chunks/update-child-chunk", "metadata": { "title": "Update Child Chunk", "sidebarTitle": "Update Child Chunk" } } }, "delete": { "tags": [ "Chunks" ], "summary": "Delete Child Chunk", "description": "Permanently delete a child chunk from its parent chunk.", "operationId": "deleteChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)." }, { "name": "child_chunk_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Child chunk ID." } ], "responses": { "204": { "description": "Success." }, "400": { "description": "`invalid_param` : Removing the child chunk index from the vector store failed; the message carries the underlying vector-store error.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Vector store operation failed: [Errno 111] Connection refused" } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (upgrade plan)", "value": { "status": 403, "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan." } } } } } }, "404": { "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.\n- `not_found` : Child chunk not found.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } }, "not_found_4": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Child chunk not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/chunks/delete-child-chunk", "metadata": { "title": "Delete Child Chunk", "sidebarTitle": "Delete Child Chunk" } } } }, "/datasets/{dataset_id}/retrieve": { "post": { "tags": [ "Knowledge Bases" ], "summary": "Retrieve Chunks from a Knowledge Base / Test Retrieval", "description": "Searches a knowledge base and returns the chunks most relevant to the query, for both production retrieval and test retrieval.", "operationId": "retrieveSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 250, "description": "Search query text." }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "List of attachment IDs to include in the retrieval context." }, "external_retrieval_model": { "type": "object", "description": "Retrieval settings for external knowledge bases.", "properties": { "top_k": { "type": "integer", "description": "Maximum number of results to return." }, "score_threshold": { "type": "number", "description": "Minimum similarity score threshold for filtering results." }, "score_threshold_enabled": { "type": "boolean", "description": "Whether score threshold filtering is enabled." } } } } } } } }, "responses": { "200": { "description": "Retrieval results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "description": "The original query object.", "properties": { "content": { "type": "string", "description": "The query text." } } }, "records": { "type": "array", "description": "List of matched retrieval records.", "items": { "type": "object", "properties": { "segment": { "type": "object", "description": "Matched chunk from the knowledge base.", "properties": { "id": { "type": "string", "description": "Unique identifier of the chunk." }, "position": { "type": "integer", "description": "Position of the chunk within the document." }, "document_id": { "type": "string", "description": "ID of the document this chunk belongs to." }, "content": { "type": "string", "description": "Text content of the chunk." }, "sign_content": { "type": "string", "description": "Signed content hash for integrity verification." }, "answer": { "type": "string", "description": "Answer content, used in Q&A mode documents." }, "word_count": { "type": "integer", "description": "Word count of the chunk content." }, "tokens": { "type": "integer", "description": "Token count of the chunk content." }, "keywords": { "type": "array", "description": "Keywords associated with this chunk for keyword-based retrieval.", "items": { "type": "string" } }, "index_node_id": { "type": "string", "description": "ID of the index node in the vector store." }, "index_node_hash": { "type": "string", "description": "Hash of the indexed content, used to detect changes." }, "hit_count": { "type": "integer", "description": "Number of times this chunk has been matched in retrieval queries." }, "enabled": { "type": "boolean", "description": "Whether the chunk is enabled for retrieval." }, "disabled_at": { "type": "number", "nullable": true, "description": "Timestamp when the chunk was disabled. `null` if enabled." }, "disabled_by": { "type": "string", "nullable": true, "description": "ID of the user who disabled the chunk. `null` if enabled." }, "status": { "type": "string", "description": "Indexing status of the chunk." }, "created_by": { "type": "string", "description": "ID of the user who created the chunk." }, "created_at": { "type": "number", "description": "Creation timestamp (Unix epoch in seconds)." }, "indexing_at": { "type": "number", "nullable": true, "description": "Timestamp when indexing started. `null` if not yet started." }, "completed_at": { "type": "number", "nullable": true, "description": "Timestamp when indexing completed. `null` if not yet completed." }, "error": { "type": "string", "nullable": true, "description": "Error message if indexing failed. `null` when no error." }, "stopped_at": { "type": "number", "nullable": true, "description": "Timestamp when indexing was stopped. `null` if not stopped." }, "document": { "type": "object", "description": "Parent document information for the matched chunk.", "properties": { "id": { "type": "string", "description": "Unique identifier of the document." }, "data_source_type": { "type": "string", "description": "How the document was created." }, "name": { "type": "string", "description": "Document name." }, "doc_type": { "type": "string", "nullable": true, "description": "Document type classification. `null` if not set." }, "doc_metadata": { "type": "object", "nullable": true, "description": "Metadata values for the document. `null` if no metadata is configured." } } } } }, "child_chunks": { "type": "array", "description": "Matched child chunks within the chunk, if using hierarchical indexing.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the child chunk." }, "content": { "type": "string", "description": "Text content of the child chunk." }, "position": { "type": "integer", "description": "Position of the child chunk within the parent chunk." }, "score": { "type": "number", "description": "Similarity score of the child chunk." } } } }, "score": { "type": "number", "description": "Similarity score." }, "tsne_position": { "type": "object", "nullable": true, "description": "t-SNE visualization position." }, "files": { "type": "array", "description": "Files attached to this chunk.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachment file identifier." }, "name": { "type": "string", "description": "Original file name." }, "size": { "type": "integer", "description": "File size in bytes." }, "extension": { "type": "string", "description": "File extension." }, "mime_type": { "type": "string", "description": "MIME type of the file." }, "source_url": { "type": "string", "description": "URL to access the attachment." } } } }, "summary": { "type": "string", "nullable": true, "description": "Summary content if retrieved via summary index." } } } } } }, "examples": { "success": { "summary": "Response Example", "value": { "query": { "content": "What is Dify?" }, "records": [ { "segment": { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 1, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "data_source_type": "upload_file", "name": "guide.txt", "doc_type": null, "doc_metadata": null } }, "child_chunks": [], "score": 0.92, "tsne_position": null, "files": [], "summary": null } ] } } } } } }, "400": { "description": "- `dataset_not_initialized` : The knowledge base is still initializing or indexing.\n- `provider_not_initialize` : The model provider has no valid credentials configured.\n- `provider_quota_exceeded` : The Dify-hosted model provider quota is exhausted.\n- `model_currently_not_support` : The selected model is not currently supported.\n- `completion_request_error` : The model request failed.\n- `invalid_param` : A request parameter is invalid.", "content": { "application/json": { "examples": { "dataset_not_initialized": { "summary": "dataset_not_initialized", "value": { "status": 400, "code": "dataset_not_initialized", "message": "The dataset is still being initialized or indexing. Please wait a moment." } }, "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 Model Provider has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Invalid parameter value." } } } } } }, "403": { "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : Your subscription's knowledge base request rate limit has been reached.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : No knowledge base matches `dataset_id`.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } }, "500": { "description": "`internal_server_error` : An internal error occurred during retrieval.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "An internal error occurred." } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval", "metadata": { "title": "Retrieve Chunks from a Knowledge Base / Test Retrieval", "sidebarTitle": "Retrieve Chunks from a Knowledge Base / Test Retrieval" } } } }, "/datasets/tags": { "post": { "tags": [ "Tags" ], "summary": "Create Knowledge Tag", "description": "Create a tag for organizing knowledge bases.", "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Tag name. Must be unique within the workspace." } } } } } }, "responses": { "200": { "description": "Tag created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag identifier." }, "name": { "type": "string", "description": "Tag display name." }, "type": { "type": "string", "description": "Tag type. Always `knowledge` for knowledge base tags." }, "binding_count": { "type": "string", "nullable": true, "description": "Number of knowledge bases bound to this tag." } } }, "examples": { "success": { "summary": "Response Example", "value": { "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs", "type": "knowledge", "binding_count": "0" } } } } } }, "400": { "description": "`invalid_param` : A knowledge tag with the same name already exists.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Tag name already exists" } } } } } } }, "x-mint": { "href": "/en/api-reference/tags/create-knowledge-tag", "metadata": { "title": "Create Knowledge Tag", "sidebarTitle": "Create Knowledge Tag" } } }, "get": { "tags": [ "Tags" ], "summary": "List Knowledge Tags", "description": "Returns all knowledge base tags in the workspace.", "operationId": "getKnowledgeTags", "responses": { "200": { "description": "List of tags.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag identifier." }, "name": { "type": "string", "description": "Tag display name." }, "type": { "type": "string", "description": "Tag type. Always `knowledge` for knowledge base tags." }, "binding_count": { "type": "string", "nullable": true, "description": "Number of knowledge bases bound to this tag." } } } }, "examples": { "success": { "summary": "Response Example", "value": [ { "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs", "type": "knowledge", "binding_count": "0" } ] } } } } } }, "x-mint": { "href": "/en/api-reference/tags/list-knowledge-tags", "metadata": { "title": "List Knowledge Tags", "sidebarTitle": "List Knowledge Tags" } } }, "patch": { "tags": [ "Tags" ], "summary": "Update Knowledge Tag", "description": "Rename a knowledge base tag.", "operationId": "updateKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tag_id", "name" ], "properties": { "tag_id": { "type": "string", "description": "ID of the tag to rename. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags)." }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "New name for the tag. Must be unique within the workspace." } } } } } }, "responses": { "200": { "description": "Tag updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag identifier." }, "name": { "type": "string", "description": "Tag display name." }, "type": { "type": "string", "description": "Tag type. Always `knowledge` for knowledge base tags." }, "binding_count": { "type": "string", "nullable": true, "description": "Number of knowledge bases bound to this tag." } } }, "examples": { "success": { "summary": "Response Example", "value": { "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs", "type": "knowledge", "binding_count": "0" } } } } } }, "400": { "description": "`invalid_param` : A knowledge tag with the same name already exists.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Tag name already exists" } } } } } }, "404": { "description": "`not_found` : The specified tag does not exist.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Tag not found" } } } } } } }, "x-mint": { "href": "/en/api-reference/tags/update-knowledge-tag", "metadata": { "title": "Update Knowledge Tag", "sidebarTitle": "Update Knowledge Tag" } } }, "delete": { "tags": [ "Tags" ], "summary": "Delete Knowledge Tag", "description": "Permanently delete a knowledge base tag. Does not delete the knowledge bases that were tagged.", "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tag_id" ], "properties": { "tag_id": { "type": "string", "description": "ID of the tag to delete. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags)." } } } } } }, "responses": { "204": { "description": "Success." }, "404": { "description": "`not_found` : The specified tag does not exist.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Tag not found" } } } } } } }, "x-mint": { "href": "/en/api-reference/tags/delete-knowledge-tag", "metadata": { "title": "Delete Knowledge Tag", "sidebarTitle": "Delete Knowledge Tag" } } } }, "/datasets/tags/binding": { "post": { "tags": [ "Tags" ], "summary": "Create Tag Binding", "description": "Bind one or more tags to a knowledge base. A knowledge base can have multiple tags.", "operationId": "bindTagsToDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tag_ids", "target_id" ], "properties": { "tag_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "IDs of the tags to bind. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags). Unknown tag IDs are silently ignored." }, "target_id": { "type": "string", "description": "Knowledge base to bind the tags to. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } } } } } }, "responses": { "204": { "description": "Success." }, "404": { "description": "`not_found` : The target knowledge base does not exist.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found" } } } } } } }, "x-mint": { "href": "/en/api-reference/tags/create-tag-binding", "metadata": { "title": "Create Tag Binding", "sidebarTitle": "Create Tag Binding" } } } }, "/datasets/tags/unbinding": { "post": { "tags": [ "Tags" ], "summary": "Delete Tag Binding", "description": "Remove one or more tags from a knowledge base.", "operationId": "unbindTagFromDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_id" ], "properties": { "tag_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Tag IDs to unbind. Required unless the legacy `tag_id` is provided. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags)." }, "tag_id": { "type": "string", "deprecated": true, "description": "Legacy single-tag form. Normalized into `tag_ids` server-side. Use `tag_ids` for new integrations." }, "target_id": { "type": "string", "description": "Knowledge base to unbind the tags from. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } } } } } }, "responses": { "204": { "description": "Success." }, "404": { "description": "`not_found` : The target knowledge base does not exist.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found" } } } } } } }, "x-mint": { "href": "/en/api-reference/tags/delete-tag-binding", "metadata": { "title": "Delete Tag Binding", "sidebarTitle": "Delete Tag Binding" } } } }, "/datasets/{dataset_id}/tags": { "get": { "tags": [ "Tags" ], "summary": "Get Knowledge Base Tags", "description": "Returns the tags bound to a knowledge base.", "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "responses": { "200": { "description": "Tags bound to the knowledge base.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "List of tags bound to this knowledge base.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag identifier." }, "name": { "type": "string", "description": "Tag display name." } } } }, "total": { "type": "integer", "description": "Total number of tags bound to this knowledge base." } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs" } ], "total": 1 } } } } } }, "403": { "description": "`forbidden` : Dataset api access is not enabled.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/tags/get-knowledge-base-tags", "metadata": { "title": "Get Knowledge Base Tags", "sidebarTitle": "Get Knowledge Base Tags" } } } }, "/datasets/{dataset_id}/metadata": { "post": { "tags": [ "Metadata" ], "summary": "Create Metadata Field", "description": "Create a custom metadata field for annotating documents in the knowledge base with structured information.", "operationId": "createMetadataField", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "string", "number", "time" ], "description": "`string` for text values, `number` for numeric values, `time` for date/time values." }, "name": { "type": "string", "description": "Name for the metadata field. Must be unique among the knowledge base's fields and at most 255 characters." } } } } } }, "responses": { "201": { "description": "Metadata field created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Metadata field identifier." }, "name": { "type": "string", "description": "Metadata field name." }, "type": { "type": "string", "description": "Metadata field type." } } }, "examples": { "success": { "summary": "Response Example", "value": { "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", "name": "author", "type": "string" } } } } } }, "400": { "description": "`invalid_param` : The metadata name already exists, exceeds 255 characters, or conflicts with a built-in field.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Metadata name already exists." } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/metadata/create-metadata-field", "metadata": { "title": "Create Metadata Field", "sidebarTitle": "Create Metadata Field" } } }, "get": { "tags": [ "Metadata" ], "summary": "List Metadata Fields", "description": "Returns all metadata fields for the knowledge base, both custom and built-in, with the count of documents using each field.", "operationId": "listMetadataFields", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "responses": { "200": { "description": "Metadata fields for the knowledge base.", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc_metadata": { "type": "array", "description": "List of metadata field definitions.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Metadata field identifier." }, "name": { "type": "string", "description": "Metadata field name." }, "type": { "type": "string", "description": "Metadata field type." }, "count": { "type": "integer", "description": "Number of documents using this metadata field." } } } }, "built_in_field_enabled": { "type": "boolean", "description": "Whether built-in metadata fields are enabled for this knowledge base." } } }, "examples": { "success": { "summary": "Response Example", "value": { "doc_metadata": [ { "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", "name": "author", "type": "string", "count": 3 } ], "built_in_field_enabled": true } } } } } }, "403": { "description": "`forbidden` : Dataset api access is not enabled.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/metadata/list-metadata-fields", "metadata": { "title": "List Metadata Fields", "sidebarTitle": "List Metadata Fields" } } } }, "/datasets/{dataset_id}/metadata/{metadata_id}": { "patch": { "tags": [ "Metadata" ], "summary": "Update Metadata Field", "description": "Rename a custom metadata field.", "operationId": "updateMetadataField", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "metadata_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the metadata field to rename. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "New name for the field. Must be unique among the knowledge base's fields and at most 255 characters." } } } } } }, "responses": { "200": { "description": "Metadata field updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Metadata field identifier." }, "name": { "type": "string", "description": "Metadata field name." }, "type": { "type": "string", "description": "Metadata field type." } } }, "examples": { "success": { "summary": "Response Example", "value": { "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", "name": "author", "type": "string" } } } } } }, "400": { "description": "`invalid_param` : The metadata name already exists, exceeds 255 characters, or conflicts with a built-in field.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Metadata name already exists." } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/metadata/update-metadata-field", "metadata": { "title": "Update Metadata Field", "sidebarTitle": "Update Metadata Field" } } }, "delete": { "tags": [ "Metadata" ], "summary": "Delete Metadata Field", "description": "Permanently delete a custom metadata field. Documents that used the field lose their values for it.", "operationId": "deleteMetadataField", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "metadata_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the metadata field to delete. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields)." } ], "responses": { "204": { "description": "Success." }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/metadata/delete-metadata-field", "metadata": { "title": "Delete Metadata Field", "sidebarTitle": "Delete Metadata Field" } } } }, "/datasets/{dataset_id}/metadata/built-in": { "get": { "tags": [ "Metadata" ], "summary": "Get Built-in Metadata Fields", "description": "Returns the built-in metadata fields provided by the system.", "operationId": "getBuiltInMetadataFields", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "responses": { "200": { "description": "Built-in metadata fields.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "description": "List of system-provided metadata fields.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Built-in field identifier. `document_name` for the document title, `uploader` for the creator, `upload_date` for creation time, `last_update_date` for last modification time, `source` for the document origin." }, "type": { "type": "string", "description": "Field data type. `string` for text values, `time` for date/time values." } } } } } }, "examples": { "success": { "summary": "Response Example", "value": { "fields": [ { "name": "document_name", "type": "string" }, { "name": "uploader", "type": "string" }, { "name": "upload_date", "type": "time" }, { "name": "last_update_date", "type": "time" }, { "name": "source", "type": "string" } ] } } } } } }, "403": { "description": "`forbidden` : Dataset api access is not enabled.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/metadata/get-built-in-metadata-fields", "metadata": { "title": "Get Built-in Metadata Fields", "sidebarTitle": "Get Built-in Metadata Fields" } } } }, "/datasets/{dataset_id}/metadata/built-in/{action}": { "post": { "tags": [ "Metadata" ], "summary": "Update Built-in Metadata Field", "description": "Enable or disable built-in metadata fields for the knowledge base.", "operationId": "toggleBuiltInMetadataField", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "enable", "disable" ] }, "description": "`enable` to activate built-in metadata fields, `disable` to deactivate them." } ], "responses": { "200": { "description": "Built-in metadata field toggled successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "Operation result." } } }, "examples": { "success": { "summary": "Response Example", "value": { "result": "success" } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/metadata/update-built-in-metadata-field", "metadata": { "title": "Update Built-in Metadata Field", "sidebarTitle": "Update Built-in Metadata Field" } } } }, "/datasets/{dataset_id}/documents/metadata": { "post": { "tags": [ "Metadata" ], "summary": "Update Document Metadata in Batch", "description": "Update metadata values for multiple documents in a single request.", "operationId": "batchUpdateDocumentMetadata", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operation_data" ], "properties": { "operation_data": { "type": "array", "items": { "type": "object", "required": [ "document_id", "metadata_list" ], "properties": { "document_id": { "type": "string", "description": "ID of the document to update. See [List Documents](/en/api-reference/documents/list-documents)." }, "metadata_list": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Metadata field ID. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields)." }, "name": { "type": "string", "description": "Metadata field name." }, "value": { "description": "Metadata value. Can be a string, number, or `null`." } } }, "description": "Metadata fields to set on the document." }, "partial_update": { "type": "boolean", "default": false, "description": "Whether to partially update metadata, keeping existing values for unspecified fields." } } }, "description": "Document metadata update operations, one entry per document." } } } } } }, "responses": { "200": { "description": "Document metadata updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "Operation result." } } }, "examples": { "success": { "summary": "Response Example", "value": { "result": "success" } } } } } }, "400": { "description": "`invalid_param` : Another metadata operation is already running for a document in this request.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Another document metadata operation is running, please wait a moment." } } } } } }, "403": { "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : Knowledge base not found.\n- `not_found` : A document referenced in `operation_data` does not exist in this knowledge base.\n- `not_found` : A metadata field referenced in `metadata_list` does not exist in this knowledge base.", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found (knowledge base)", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found (document)", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found (metadata)", "value": { "status": 404, "code": "not_found", "message": "Metadata not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/metadata/update-document-metadata-in-batch", "metadata": { "title": "Update Document Metadata in Batch", "sidebarTitle": "Update Document Metadata in Batch" } } } }, "/workspaces/current/models/model-types/{model_type}": { "get": { "tags": [ "Models" ], "summary": "Get Available Models", "description": "Returns the available models of a given type. Use it to find the `text-embedding` and `rerank` models to configure on a knowledge base.", "operationId": "getAvailableModels", "parameters": [ { "name": "model_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "text-embedding", "rerank", "llm", "tts", "speech2text", "moderation" ] }, "description": "Type of model to retrieve. For knowledge base configuration, use `text-embedding` for embedding models or `rerank` for reranking models." } ], "responses": { "200": { "description": "Available models for the specified type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "List of model providers with their available models.", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). Legacy providers may return the bare short form (e.g. `openai`)." }, "label": { "type": "object", "description": "Localized display name of the provider.", "properties": { "en_US": { "type": "string", "description": "English display name." }, "zh_Hans": { "type": "string", "description": "Chinese display name." } } }, "icon_small": { "type": "object", "description": "URL of the provider's small icon.", "properties": { "en_US": { "type": "string", "description": "Small icon URL." }, "zh_Hans": { "type": "string", "description": "Chinese icon URL." } } }, "status": { "type": "string", "description": "Provider status. `active` when credentials are configured and valid." }, "models": { "type": "array", "description": "List of available models from this provider.", "items": { "type": "object", "properties": { "model": { "type": "string", "description": "Model identifier. Use this as the `embedding_model` value when creating or updating a knowledge base." }, "label": { "type": "object", "description": "Localized display name of the model.", "properties": { "en_US": { "type": "string", "description": "English model name." }, "zh_Hans": { "type": "string", "description": "Chinese model name." } } }, "model_type": { "type": "string", "description": "Type of the model, matching the `model_type` path parameter." }, "features": { "type": "array", "nullable": true, "description": "Supported features of the model, `null` if none.", "items": { "type": "string" } }, "fetch_from": { "type": "string", "description": "Where the model definition comes from. `predefined-model` for built-in models, `customizable-model` for user-configured models." }, "model_properties": { "type": "object", "description": "Model-specific properties such as `context_size`." }, "status": { "type": "string", "description": "Model availability status. `active` when ready to use." }, "deprecated": { "type": "boolean", "description": "Whether the model is deprecated." }, "load_balancing_enabled": { "type": "boolean", "description": "Whether load balancing is enabled for the model." }, "has_invalid_load_balancing_configs": { "type": "boolean", "description": "Whether the model has invalid load-balancing configurations." } } } }, "tenant_id": { "type": "string", "description": "Workspace ID the provider configuration belongs to." }, "icon_small_dark": { "type": "object", "description": "Dark-mode icon URLs; `null` when the provider has none.", "properties": { "en_US": { "type": "string" }, "zh_Hans": { "type": "string" } } } } } } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "provider": "langgenius/openai/openai", "label": { "en_US": "OpenAI", "zh_Hans": "OpenAI" }, "icon_small": { "en_US": "https://example.com/openai-small.svg", "zh_Hans": "https://example.com/openai-small.svg" }, "status": "active", "models": [ { "model": "text-embedding-3-small", "label": { "en_US": "text-embedding-3-small", "zh_Hans": "text-embedding-3-small" }, "model_type": "text-embedding", "features": null, "fetch_from": "predefined-model", "model_properties": { "context_size": 8191 }, "status": "active", "deprecated": false, "load_balancing_enabled": false, "has_invalid_load_balancing_configs": false } ], "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "icon_small_dark": null } ] } } } } } } }, "x-mint": { "href": "/en/api-reference/models/get-available-models", "metadata": { "title": "Get Available Models", "sidebarTitle": "Get Available Models" } } } }, "/datasets/pipeline/file-upload": { "post": { "tags": [ "Knowledge Pipeline" ], "summary": "Upload Pipeline File", "description": "Uploads a file for use in a knowledge pipeline. Use the returned `id` as the `reference` of a `local_file` item in [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline).", "operationId": "uploadPipelineFile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload, as one `multipart/form-data` part. Document files are capped at 15 MB by default.\n\nSelf-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments).\n\nOn Dify Cloud, Professional and Team plans raise the document cap to 50 MB. Images, audio, and video follow their own limits: 10 MB, 50 MB, and 100 MB by default." } } } } } }, "responses": { "201": { "description": "File uploaded successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the uploaded file." }, "name": { "type": "string", "description": "Original file name." }, "size": { "type": "integer", "description": "File size in bytes." }, "extension": { "type": "string", "description": "File extension." }, "mime_type": { "type": "string", "nullable": true, "description": "MIME type of the file. May be `null` if the upload did not include one." }, "created_by": { "type": "string", "description": "ID of the user who uploaded the file." }, "created_at": { "type": "string", "nullable": true, "description": "Upload timestamp in ISO 8601 format. May be `null` while the record is being created." } } }, "examples": { "success": { "summary": "Response Example", "value": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "report.pdf", "size": 524288, "extension": "pdf", "mime_type": "application/pdf", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": "2025-03-06T12:00:00" } } } } } }, "400": { "description": "- `no_file_uploaded` : No file was provided in the request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `too_many_files` : Only one file is allowed per request.", "content": { "application/json": { "examples": { "no_file_uploaded": { "summary": "no_file_uploaded", "value": { "status": 400, "code": "no_file_uploaded", "message": "Please upload your file." } }, "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "status": 400, "code": "filename_not_exists_error", "message": "The specified filename does not exist." } }, "too_many_files": { "summary": "too_many_files", "value": { "status": 400, "code": "too_many_files", "message": "Only one file is allowed." } } } } } }, "413": { "description": "`file_too_large` : The file exceeds the upload size limit.", "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` : The file type is not supported.", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-pipeline/upload-pipeline-file", "metadata": { "title": "Upload Pipeline File", "sidebarTitle": "Upload Pipeline File" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/pipeline/file-upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf'" } ] } }, "/datasets/{dataset_id}/pipeline/datasource-plugins": { "get": { "tags": [ "Knowledge Pipeline" ], "summary": "List Datasource Plugins", "description": "Returns the datasource nodes configured in the knowledge pipeline, each with the plugin it uses and the metadata needed to run it.", "operationId": "listDatasourcePlugins", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "is_published", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "Whether to read nodes from the published pipeline version rather than the draft." } ], "responses": { "200": { "description": "List of datasource nodes configured in the pipeline.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "node_id": { "type": "string", "description": "ID of the datasource node in the pipeline workflow. Pass this as `node_id` to [Run Datasource Node](/en/api-reference/knowledge-pipeline/run-datasource-node), or as `start_node_id` to [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline)." }, "plugin_id": { "type": "string", "description": "ID of the datasource plugin providing this node." }, "provider_name": { "type": "string", "description": "Provider name registered by the datasource plugin." }, "datasource_type": { "type": "string", "description": "Type of datasource. One of `local_file`, `online_document`, `online_drive`, `website_crawl`." }, "title": { "type": "string", "description": "Display title configured for the node." }, "user_input_variables": { "type": "array", "description": "Pipeline input variables the caller must supply for this datasource, derived from `{{#...#}}` references in the node's datasource parameters. Each item follows the pipeline variable schema used by the workflow.", "items": { "type": "object", "additionalProperties": true } }, "credentials": { "type": "array", "description": "Credentials available for authenticating with this datasource.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Credential ID. Pass this as `credential_id` to [Run Datasource Node](/en/api-reference/knowledge-pipeline/run-datasource-node) or in per-item `credential_id` fields of [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline)." }, "name": { "type": "string", "description": "Display name of the credential." }, "type": { "type": "string", "description": "Credential type defined by the datasource plugin." }, "is_default": { "type": "boolean", "description": "Whether this credential is the default for the provider." } } } } } } }, "examples": { "success": { "summary": "Response Example", "value": [ { "node_id": "1719288585006", "plugin_id": "langgenius/notion_datasource", "provider_name": "notion", "datasource_type": "online_document", "title": "Notion Documents", "user_input_variables": [], "credentials": [ { "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "name": "Production Notion", "type": "api-key", "is_default": true } ] } ] } } } } }, "400": { "description": "`invalid_param` : The knowledge base has no processing pipeline configured.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Pipeline not found" } } } } } }, "403": { "description": "`forbidden` : API access is not enabled for this knowledge base.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : No knowledge base matches `dataset_id`.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-pipeline/list-datasource-plugins", "metadata": { "title": "List Datasource Plugins", "sidebarTitle": "List Datasource Plugins" } } } }, "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": { "post": { "tags": [ "Knowledge Pipeline" ], "summary": "Run Datasource Node", "description": "Runs a single datasource node in the knowledge pipeline and streams its execution events.", "operationId": "runDatasourceNode", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." }, { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the datasource node to run, from [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs", "datasource_type", "is_published" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "Input variables for the datasource node." }, "datasource_type": { "type": "string", "enum": [ "online_document", "local_file", "website_crawl", "online_drive" ], "description": "Type of the datasource." }, "credential_id": { "type": "string", "nullable": true, "description": "ID of the credential to authenticate with the datasource, from the `credentials` array of [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins)." }, "is_published": { "type": "boolean", "description": "Whether to run the published version of the node instead of the draft." } } } } } }, "responses": { "200": { "description": "Streaming response with node execution events.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream of node execution progress and results. See [SSE Streaming](/en/api-reference/guides/streaming) for parsing." } } } }, "400": { "description": "`invalid_param` : The knowledge base has no processing pipeline configured, or the request body failed validation.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Pipeline not found" } } } } } }, "403": { "description": "`forbidden` : API access is not enabled for this knowledge base.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : No knowledge base matches `dataset_id`.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-pipeline/run-datasource-node", "metadata": { "title": "Run Datasource Node", "sidebarTitle": "Run Datasource Node" } } } }, "/datasets/{dataset_id}/pipeline/run": { "post": { "tags": [ "Knowledge Pipeline" ], "summary": "Run Pipeline", "description": "Runs the full knowledge pipeline over one or more datasources. `response_mode` selects a streaming or blocking response.", "operationId": "runPipeline", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs", "datasource_type", "datasource_info_list", "start_node_id", "is_published", "response_mode" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "Key-value pairs for pipeline input variables defined in the workflow. Pass `{}` if the pipeline has no input variables." }, "datasource_type": { "type": "string", "enum": [ "local_file", "online_document", "website_crawl", "online_drive" ], "description": "Type of the datasource. Determines which fields are expected in `datasource_info_list` items." }, "datasource_info_list": { "type": "array", "description": "List of datasource objects to process. The expected item structure depends on `datasource_type`.", "items": { "oneOf": [ { "title": "Local File", "type": "object", "required": [ "reference" ], "properties": { "reference": { "type": "string", "description": "Use the `id` returned by the [Upload Pipeline File](/en/api-reference/knowledge-pipeline/upload-pipeline-file) endpoint. `related_id` is accepted as an alias." }, "name": { "type": "string", "description": "Document title. Defaults to `\"untitled\"`." } } }, { "title": "Online Document", "type": "object", "required": [ "workspace_id", "page" ], "properties": { "workspace_id": { "type": "string", "description": "ID of the workspace or database in the external platform (e.g., a Notion workspace ID)." }, "page": { "type": "object", "description": "Page details.", "required": [ "page_id", "type" ], "properties": { "page_id": { "type": "string", "description": "Page identifier." }, "type": { "type": "string", "description": "Page type defined by the datasource plugin (e.g., `\"page\"`, `\"database\"`)." }, "page_name": { "type": "string", "description": "Display name. Defaults to `\"untitled\"`." } } }, "credential_id": { "type": "string", "description": "Credential for authenticating with the external platform. Managed via the Dify console. If omitted, the provider's default credential is used." } } }, { "title": "Website Crawl", "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "URL to crawl." }, "title": { "type": "string", "description": "Used as the document name. Defaults to `\"untitled\"`." } } }, { "title": "Online Drive", "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "File or folder ID." }, "type": { "type": "string", "enum": [ "file", "folder" ], "description": "Whether this entry is a single file or a folder to expand." }, "bucket": { "type": "string", "description": "Storage bucket name. Required by some drive providers (e.g., S3-compatible stores); omit if the provider does not use buckets." }, "name": { "type": "string", "description": "File name. Defaults to `\"untitled\"`." } } } ] } }, "start_node_id": { "type": "string", "description": "ID of the node to start execution from, from [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins)." }, "is_published": { "type": "boolean", "description": "Whether to run the published version of the pipeline instead of the current draft. Run the draft to test unpublished changes." }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "Response mode for the pipeline execution. `streaming` returns a Server-Sent Events stream, `blocking` waits and returns the complete result." } } }, "examples": { "local_file": { "summary": "Request Example - Local file", "value": { "inputs": {}, "datasource_type": "local_file", "datasource_info_list": [ { "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "quarterly-report.pdf" } ], "start_node_id": "1719288585006", "is_published": true, "response_mode": "blocking" } }, "online_document": { "summary": "Request Example - Online document", "value": { "inputs": {}, "datasource_type": "online_document", "datasource_info_list": [ { "workspace_id": "ws-abc123", "page": { "page_id": "pg-def456", "type": "page", "page_name": "Product Roadmap" }, "credential_id": "cred-789xyz" } ], "start_node_id": "1719288585006", "is_published": true, "response_mode": "streaming" } }, "website_crawl": { "summary": "Request Example - Website crawl", "value": { "inputs": {}, "datasource_type": "website_crawl", "datasource_info_list": [ { "url": "https://example.com/docs/getting-started", "title": "Getting Started Guide" } ], "start_node_id": "1719288585006", "is_published": true, "response_mode": "blocking" } }, "online_drive": { "summary": "Request Example - Online drive", "value": { "inputs": {}, "datasource_type": "online_drive", "datasource_info_list": [ { "id": "file-abc123", "type": "file", "bucket": "my-bucket", "name": "meeting-notes.docx" } ], "start_node_id": "1719288585006", "is_published": true, "response_mode": "blocking" } } } } } }, "responses": { "200": { "description": "Pipeline execution result. Format depends on `response_mode`: streaming returns a `text/event-stream`, blocking returns a JSON object.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream. Returned when `response_mode` is `streaming`; see [SSE Streaming](/en/api-reference/guides/streaming) for the wire format.\n\nKey events:\n\n- `workflow_started`: execution began\n- `node_started` / `node_finished`: per-node progress with `node_id`, `node_type`, `status`, `inputs`, `outputs`\n- `workflow_finished`: final result with `status`, `outputs`, `total_tokens`, `elapsed_time`\n- `ping`: keepalive" } }, "application/json": { "schema": { "type": "object", "description": "Complete pipeline execution result. Returned when `response_mode` is `blocking`.", "additionalProperties": true }, "examples": { "success": { "summary": "Blocking Response Example", "value": { "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", "data": { "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", "status": "succeeded", "outputs": {}, "created_at": 1741267200, "finished_at": 1741267210 } } } } } } }, "400": { "description": "`invalid_param` : The knowledge base has no processing pipeline configured, or the request body failed validation.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Pipeline not found" } } } } } }, "403": { "description": "`forbidden` : API access is not enabled for this knowledge base.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : No knowledge base matches `dataset_id`.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } }, "500": { "description": "`pipeline_run_error` : Pipeline execution failed.", "content": { "application/json": { "examples": { "pipeline_run_error": { "summary": "pipeline_run_error", "value": { "status": 500, "code": "pipeline_run_error", "message": "Pipeline execution failed: connection timeout" } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-pipeline/run-pipeline", "metadata": { "title": "Run Pipeline", "sidebarTitle": "Run Pipeline" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)).\n\nKeep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`)." } }, "responses": { "SuccessResult": { "description": "Operation successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "Operation result. Always `success`." } } }, "examples": { "success": { "summary": "Response Example", "value": { "result": "success" } } } } } } }, "schemas": { "ChatRequest": { "type": "object", "required": [ "inputs", "query", "user" ], "properties": { "query": { "type": "string", "description": "The user's message." }, "inputs": { "type": "object", "description": "Values for the app's input variables, keyed by variable name. The expected names and types come from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).", "additionalProperties": true }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "Mode of response return. Defaults to blocking when omitted.\n\n- `streaming` (recommended): the reply arrives as Server-Sent Events.\n- `blocking`: returns once generation completes. Long generations risk interruption: on Dify Cloud, the edge proxy may end the connection if the response doesn't arrive within its timeout.\n- Legacy Agent and Agent apps support `streaming` only; a `blocking` request fails with 400." }, "user": { "type": "string", "description": "End-user identifier, defined by your app and unique within it. Conversations, messages, and files are visible only to requests carrying the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity)." }, "conversation_id": { "type": "string", "description": "ID of the conversation to continue. Omit it or pass an empty string to start a new conversation; the response returns a `conversation_id` to send with the next message. To resume an earlier conversation, get its ID from [List Conversations](/en/api-reference/conversations/list-conversations)." }, "files": { "type": "array", "description": "Files to attach to the message. For a local file, first upload it via [Upload File](/en/api-reference/files/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`. Agent apps accept file references but do not process their contents.", "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](/en/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](/en/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation.", "default": true }, "workflow_id": { "type": "string", "description": "Chatflow apps only. Specify a published workflow version ID to execute. If not provided, the latest published version is used. On Dify Cloud, pinning a version requires a paid plan." } } }, "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. `chat` for Chatbot apps, `agent-chat` for Legacy Agent apps, `advanced-chat` for Chatflow apps." }, "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", "agent_message", "agent_thought", "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", "agent_message": "#/components/schemas/StreamEventChatAgentMessage", "tts_message": "#/components/schemas/StreamEventChatTtsMessage", "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", "agent_thought": "#/components/schemas/StreamEventChatAgentThought", "message_file": "#/components/schemas/StreamEventChatMessageFile", "message_end": "#/components/schemas/StreamEventChatMessageEnd", "message_replace": "#/components/schemas/StreamEventChatMessageReplace", "error": "#/components/schemas/StreamEventChatError", "ping": "#/components/schemas/StreamEventChatPing", "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" } } }, "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." } } } ] }, "StreamEventChatAgentMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "answer": { "type": "string", "description": "LLM returned text chunk (Agent mode)." } } } ] }, "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." } } } ] }, "StreamEventChatAgentThought": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "Agent thought, LLM thinking, tool call details (Agent mode).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent thought ID." }, "position": { "type": "integer", "description": "Position of this thought in the sequence for the message." }, "thought": { "type": "string", "description": "What LLM is thinking." }, "observation": { "type": "string", "description": "Response from tool calls." }, "tool": { "type": "string", "description": "List of tools called, split by `;`." }, "tool_input": { "type": "string", "description": "Input of tools in JSON format." }, "message_files": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "File IDs of files related to this thought." } } } ] }, "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", "description": "Who this file belongs to. Always `assistant` for tool-generated files." }, "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. For Chatflow apps, a `ping` is also the first event of every stream." } ] }, "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." }, "reference": { "type": "string", "nullable": true, "description": "Opaque file reference used internally when attaching files in agent and tool contexts. Always `null` for files uploaded through this endpoint." }, "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": "End-user ID of the uploader. Look up details with [Get End User Info](/en/api-reference/end-users/get-end-user-info)." }, "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](/en/api-reference/chat-messages/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": "End-user identifier, defined by your app and unique within it. Must match the `user` that received the message, since feedback is scoped to that end user. See [End User Identity](/en/api-reference/guides/end-user-identity)." }, "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", "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" } }, "message_tokens": { "type": "integer", "description": "Number of tokens in the input message." }, "answer_tokens": { "type": "integer", "description": "Number of tokens in the generated answer." }, "total_tokens": { "type": "integer", "description": "Total tokens used, the sum of `message_tokens` and `answer_tokens`." }, "provider_response_latency": { "type": "number", "format": "double", "description": "Model provider response latency in seconds." }, "total_price": { "type": "string", "format": "decimal", "nullable": true, "description": "Total price for the tokens used, or `null` when pricing is unavailable." }, "currency": { "type": "string", "nullable": true, "description": "Currency for `total_price` (for example, `USD`), or `null` when pricing is unavailable." } } }, "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.", "properties": { "name": { "type": "string", "description": "New conversation name. Required unless `auto_generate` is `true`." }, "auto_generate": { "type": "boolean", "default": false, "description": "Automatically generate the conversation name. When `true`, the `name` field is ignored." }, "user": { "type": "string", "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)." } } }, "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": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)." } } }, "AudioToTextRequest": { "type": "object", "description": "Request body for audio-to-text conversion.", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file to transcribe. Accepted MIME types: `audio/mp3`, `audio/m4a` (also accepted as `audio/x-m4a`), `audio/wav`, `audio/amr`, `audio/mpga`. Other types, including the common `audio/mpeg`, are rejected with `unsupported_audio_type`. Maximum size `30 MB`." }, "user": { "type": "string", "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)." } } }, "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": "ID of the message whose answer to voice. Takes priority over `text` when both are provided. Get message IDs from [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages)." }, "text": { "type": "string", "description": "Text to synthesize into speech." }, "user": { "type": "string", "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)." }, "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](/en/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." }, "streaming": { "type": "boolean", "description": "Accepted for backward compatibility but has no effect. Whether the audio is streamed is determined by the configured TTS provider's output, not by this field." } } }, "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 Generator apps, `chat` for Chatbot apps, `agent-chat` for Legacy Agent apps, `advanced-chat` for Chatflow apps, `workflow` for Workflow apps, `agent` for Agent apps." }, "author_name": { "type": "string", "description": "Name of the application author." } } }, "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", "properties": { "label": { "type": "string", "description": "Display label for the form field." }, "variable": { "type": "string", "description": "Variable name used as the key in the `inputs` object." }, "required": { "type": "boolean", "description": "Whether this field must be filled before submission." }, "default": { "type": "string", "description": "Default value pre-filled in the form field." } } }, "ParagraphControl": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the form field." }, "variable": { "type": "string", "description": "Variable name used as the key in the `inputs` object." }, "required": { "type": "boolean", "description": "Whether this field must be filled before submission." }, "default": { "type": "string", "description": "Default value pre-filled in the form field." } } }, "SelectControl": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the form field." }, "variable": { "type": "string", "description": "Variable name used as the key in the `inputs` object." }, "required": { "type": "boolean", "description": "Whether a selection must be made before submission." }, "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": "Web app 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": "Web app description." }, "copyright": { "type": "string", "description": "Copyright text." }, "privacy_policy": { "type": "string", "description": "Privacy policy URL." }, "input_placeholder": { "type": "string", "nullable": true, "description": "Placeholder text shown in the web app message input box. `null` when not configured." }, "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": "Question text the app matches incoming user input against." }, "answer": { "type": "string", "description": "Answer returned when this annotation is matched." } } }, "UpdateAnnotationRequest": { "type": "object", "description": "Request body for updating an annotation.", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "description": "New question text for the annotation." }, "answer": { "type": "string", "description": "New answer text for the annotation." } } }, "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": "Embedding model provider (for example, `openai`). Get available providers from [Get Available Models](/en/api-reference/models/get-available-models)." }, "embedding_model_name": { "type": "string", "description": "Embedding model used to vectorize annotations for matching (for example, `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](/en/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](/en/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](/en/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`." } } }, "AppParametersResponse": { "type": "object", "properties": { "opening_statement": { "type": "string", "nullable": true, "description": "Opening statement text." }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "List of suggested questions." }, "suggested_questions_after_answer": { "type": "object", "description": "Configuration for suggested questions after an answer.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "speech_to_text": { "type": "object", "description": "Speech-to-text feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "text_to_speech": { "type": "object", "description": "Text-to-speech feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." }, "voice": { "type": "string", "description": "Voice identifier for TTS." }, "language": { "type": "string", "description": "Language for TTS." }, "autoPlay": { "type": "string", "description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play." } } }, "retriever_resource": { "type": "object", "description": "Knowledge retrieval citation resource configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "annotation_reply": { "type": "object", "description": "Annotation reply feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "more_like_this": { "type": "object", "description": "More-like-this feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "sensitive_word_avoidance": { "type": "object", "description": "Content moderation feature configuration.", "properties": { "enabled": { "type": "boolean", "description": "Whether this feature is enabled." } } }, "user_input_form": { "type": "array", "items": { "type": "object", "oneOf": [ { "title": "Text Input", "type": "object", "properties": { "text-input": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the input field." }, "variable": { "type": "string", "description": "Variable name used in the workflow." }, "required": { "type": "boolean", "description": "Whether this field is required." }, "default": { "type": "string", "description": "Default value for the input field." } } } } }, { "title": "Paragraph", "type": "object", "properties": { "paragraph": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the paragraph field." }, "variable": { "type": "string", "description": "Variable name used in the workflow." }, "required": { "type": "boolean", "description": "Whether this field is required." }, "default": { "type": "string", "description": "Default value for the paragraph field." } } } } }, { "title": "Select", "type": "object", "properties": { "select": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the select field." }, "variable": { "type": "string", "description": "Variable name used in the workflow." }, "required": { "type": "boolean", "description": "Whether this field is required." }, "default": { "type": "string", "description": "Default selected value." }, "options": { "type": "array", "items": { "type": "string" }, "description": "List of selectable values for this form control." } } } } } ] }, "description": "User input form configuration." }, "file_upload": { "type": "object", "description": "File upload configuration.", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether image upload is enabled." }, "number_limits": { "type": "integer", "description": "Maximum number of images that can be uploaded." }, "detail": { "type": "string", "description": "Image detail level for vision models." }, "transfer_methods": { "type": "array", "items": { "type": "string" }, "description": "Allowed transfer methods for image upload. `remote_url` for file URL, `local_file` for uploaded file." } } } } }, "system_parameters": { "type": "object", "description": "System-level parameter limits.", "properties": { "file_size_limit": { "type": "integer", "description": "Maximum general file size in MB." }, "image_file_size_limit": { "type": "integer", "description": "Maximum image file size in MB." }, "audio_file_size_limit": { "type": "integer", "description": "Maximum audio file size in MB." }, "video_file_size_limit": { "type": "integer", "description": "Maximum video file size in MB." }, "workflow_file_upload_limit": { "type": "integer", "description": "Maximum number of files per workflow execution." } } } } }, "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](/en/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](/en/api-reference/human-input/get-human-input-form) and [Submit Human Input Form](/en/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 web app-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](/en/api-reference/workflow-runs/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](/en/api-reference/human-input/submit-human-input-form))." }, "action_text": { "type": "string", "description": "Display text of the selected action." }, "submitted_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Values the recipient submitted, keyed by each form input's `output_variable_name`." } } } } } ] }, "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 `` 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 an integration 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`." } } }, "WorkflowExecutionRequest": { "type": "object", "required": [ "inputs", "user" ], "properties": { "inputs": { "type": "object", "description": "Key-value pairs for workflow input variables. Discover the variable names and types your app expects from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).\n\nFile-type variables take an array of file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" } } ] } }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events. When omitted, defaults to blocking behavior." }, "user": { "type": "string", "description": "End-user identifier, defined by your app and unique within it. Scopes data access: a workflow run and its files are only visible to later requests that carry the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity)." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, "nullable": true, "description": "File list. Suitable when files need to be combined with text for input, available only when the model supports Vision capability. To attach a local file, first upload it via [Upload File](/en/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`." } } }, "InputFileObject": { "type": "object", "required": [ "type", "transfer_method" ], "properties": { "type": { "type": "string", "enum": [ "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 (when `transfer_method` is `remote_url`)." }, "upload_file_id": { "type": "string", "description": "Uploaded file ID, obtained by uploading through the [Upload File](/en/api-reference/files/upload-file) API in advance (when `transfer_method` is `local_file`)." } }, "anyOf": [ { "properties": { "transfer_method": { "enum": [ "remote_url" ] }, "url": { "type": "string", "format": "url" } }, "required": [ "url" ], "not": { "required": [ "upload_file_id" ] } }, { "properties": { "transfer_method": { "enum": [ "local_file" ] }, "upload_file_id": { "type": "string" } }, "required": [ "upload_file_id" ], "not": { "required": [ "url" ] } } ] }, "WorkflowBlockingResponse": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/en/api-reference/workflow-runs/stop-workflow-task) to cancel a running workflow. Only valid during execution." }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail) to retrieve results after execution." }, "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } }, "ChunkWorkflowEvent": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "description": "The type of streaming event.", "enum": [ "workflow_started", "node_started", "node_finished", "node_retry", "iteration_started", "iteration_next", "iteration_completed", "loop_started", "loop_next", "loop_completed", "reasoning_chunk", "text_chunk", "workflow_finished", "tts_message", "tts_message_end", "workflow_paused", "agent_log", "human_input_required", "human_input_form_filled", "human_input_form_timeout", "error", "ping" ] } }, "discriminator": { "propertyName": "event", "mapping": { "workflow_started": "#/components/schemas/WorkflowStreamEventWorkflowStarted", "node_started": "#/components/schemas/WorkflowStreamEventNodeStarted", "node_finished": "#/components/schemas/WorkflowStreamEventNodeFinished", "node_retry": "#/components/schemas/WorkflowStreamEventNodeRetry", "iteration_started": "#/components/schemas/WorkflowStreamEventIterationStarted", "iteration_next": "#/components/schemas/WorkflowStreamEventIterationNext", "iteration_completed": "#/components/schemas/WorkflowStreamEventIterationCompleted", "loop_started": "#/components/schemas/WorkflowStreamEventLoopStarted", "loop_next": "#/components/schemas/WorkflowStreamEventLoopNext", "loop_completed": "#/components/schemas/WorkflowStreamEventLoopCompleted", "reasoning_chunk": "#/components/schemas/StreamEventReasoningChunk", "text_chunk": "#/components/schemas/StreamEventTextChunk", "workflow_finished": "#/components/schemas/WorkflowStreamEventWorkflowFinished", "tts_message": "#/components/schemas/StreamEventTtsMessage", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", "error": "#/components/schemas/StreamEventError", "ping": "#/components/schemas/StreamEventPing", "workflow_paused": "#/components/schemas/WorkflowStreamEventWorkflowPaused", "agent_log": "#/components/schemas/WorkflowStreamEventAgentLog", "human_input_required": "#/components/schemas/WorkflowStreamEventHumanInputRequired", "human_input_form_filled": "#/components/schemas/WorkflowStreamEventHumanInputFormFilled", "human_input_form_timeout": "#/components/schemas/WorkflowStreamEventHumanInputFormTimeout" } } }, "StreamEventReasoningChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "Chain-of-thought delta emitted by an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning. This stream is parallel to `text_chunk`; the `text` stream stays free of `` tags." }, "node_id": { "type": "string", "nullable": true, "description": "ID of the LLM node producing the reasoning. Lets you attribute reasoning when multiple LLM nodes run." }, "is_final": { "type": "boolean", "description": "`true` marks the end of an LLM node's reasoning phase (the \"thinking finished\" signal); it may arrive with an empty `reasoning`." } } } } } ] }, "StreamEventTextChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "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." } } } } } ] }, "StreamEventTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when this audio chunk was generated." } } } ] }, "StreamEventTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "audio": { "type": "string", "description": "Empty string. Signals the end of the audio stream." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the audio stream ended." } } } ] }, "StreamEventError": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status code of the error." }, "code": { "type": "string", "description": "Error code." }, "message": { "type": "string", "description": "Error message." } } } ] }, "StreamEventPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "type": "object", "description": "Keep-alive ping event. Delivered as an `event: ping` line with no `data:` payload. The first event of every stream is a `ping`." } ] }, "WorkflowFinishedData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Workflow run ID." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Workflow ID." }, "status": { "type": "string", "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output data from the workflow." }, "error": { "type": "string", "nullable": true, "description": "Error message if the workflow failed." }, "elapsed_time": { "type": "number", "format": "float", "description": "Total time elapsed in seconds." }, "total_tokens": { "type": "integer", "description": "Total tokens consumed across all nodes." }, "total_steps": { "type": "integer", "description": "Total number of workflow steps executed." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the workflow run was created." }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp of when the workflow run finished." }, "created_by": { "type": "object", "additionalProperties": true, "description": "Creator information. Only present in streaming `workflow_finished` events." }, "exceptions_count": { "type": "integer", "nullable": true, "description": "Number of exceptions encountered during execution. Only present in streaming `workflow_finished` events." }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true, "description": "Files generated during workflow execution. Only present in streaming `workflow_finished` events." } } }, "WorkflowStreamEventBase": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/en/api-reference/workflow-runs/stop-workflow-task) to cancel a running workflow. Only valid during execution." }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail) to retrieve results after execution." } } }, "WorkflowStreamEventWorkflowStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Workflow run ID." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Workflow ID." }, "inputs": { "type": "object", "additionalProperties": true, "description": "Input variables for this workflow run." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the workflow run started." }, "reason": { "type": "string", "description": "Reason for the workflow start. `initial` for a new execution, `resumption` when resuming from a paused state." } } } } } ] }, "WorkflowStreamEventWorkflowFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } } ] }, "WorkflowStreamEventNodeStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Node execution ID." }, "node_id": { "type": "string", "description": "Node ID in the workflow graph." }, "node_type": { "type": "string", "description": "Node type (e.g., `llm`, `code`, `template-transform`)." }, "title": { "type": "string", "description": "Display name of the node." }, "index": { "type": "integer", "description": "Execution sequence index." }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "ID of the predecessor node, if any." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Input variables for this node." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the node execution started." }, "extras": { "type": "object", "additionalProperties": true, "description": "Additional metadata for the node execution." }, "iteration_id": { "type": "string", "nullable": true, "description": "Parent iteration ID if this node runs inside an iteration." }, "loop_id": { "type": "string", "nullable": true, "description": "Parent loop ID if this node runs inside a loop." } } } } } ] }, "WorkflowStreamEventNodeFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Node execution ID." }, "node_id": { "type": "string", "description": "Node ID in the workflow graph." }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "Display name of the node." }, "index": { "type": "integer", "description": "Execution sequence index." }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "ID of the predecessor node, if any." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Input variables for this node." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Processing data generated during node execution." }, "process_data_truncated": { "type": "boolean", "description": "Whether the `process_data` was truncated." }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output data from the node." }, "outputs_truncated": { "type": "boolean", "description": "Whether the `outputs` data was truncated." }, "status": { "type": "string", "description": "Node execution status. `running` for in-progress, `succeeded` when completed, `failed` on error, `stopped` when manually halted, `exception` on unexpected failure." }, "error": { "type": "string", "nullable": true, "description": "Error message if the node failed." }, "elapsed_time": { "type": "number", "format": "float", "description": "Time elapsed in seconds." }, "execution_metadata": { "type": "object", "nullable": true, "description": "Execution metadata including token usage.", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "Total tokens consumed by this node." }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "Total cost for this node execution." }, "currency": { "type": "string", "nullable": true, "description": "Currency of the cost (e.g., `USD`)." } } }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the node execution started." }, "finished_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the node execution finished." }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "Files generated by this node." }, "iteration_id": { "type": "string", "nullable": true, "description": "Parent iteration ID if this node runs inside an iteration." }, "loop_id": { "type": "string", "nullable": true, "description": "Parent loop ID if this node runs inside a loop." } } } } } ] }, "WorkflowStreamEventNodeRetry": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Node execution ID." }, "node_id": { "type": "string", "description": "Node ID in the workflow graph." }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "Display name of the node." }, "index": { "type": "integer", "description": "Execution sequence index." }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "ID of the predecessor node, if any." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Processing data generated during node execution." }, "process_data_truncated": { "type": "boolean", "description": "Whether the `process_data` was truncated." }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "Whether the `outputs` data was truncated." }, "status": { "type": "string", "description": "Node execution status at the retry point." }, "error": { "type": "string", "nullable": true, "description": "Error message that triggered the retry." }, "elapsed_time": { "type": "number", "format": "float", "description": "Time elapsed in seconds." }, "created_at": { "type": "integer", "format": "int64" }, "finished_at": { "type": "integer", "format": "int64" }, "retry_index": { "type": "integer", "description": "Zero-based retry attempt index." }, "iteration_id": { "type": "string", "nullable": true }, "loop_id": { "type": "string", "nullable": true }, "execution_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Metadata from the node execution." }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Files produced by the node during execution." } } } } } ] }, "WorkflowStreamEventIterationStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Node execution ID." }, "node_id": { "type": "string", "description": "Iteration node ID." }, "node_type": { "type": "string", "description": "Node type (always `iteration`)." }, "title": { "type": "string", "description": "Display name of the iteration node." }, "created_at": { "type": "integer", "format": "int64" }, "inputs": { "type": "object", "additionalProperties": true, "description": "Input variables for the iteration." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Iteration metadata." }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "WorkflowStreamEventIterationNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer", "description": "Current iteration index (zero-based)." }, "created_at": { "type": "integer", "format": "int64" }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "WorkflowStreamEventIterationCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "Whether the `outputs` data was truncated." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Input variables for the iteration." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the iteration started." }, "extras": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Additional metadata for the iteration." }, "status": { "type": "string", "description": "Iteration completion status." }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float" }, "total_tokens": { "type": "integer" }, "execution_metadata": { "type": "object", "additionalProperties": true, "description": "Execution metadata including token usage." }, "finished_at": { "type": "integer", "format": "int64" }, "steps": { "type": "integer", "description": "Number of iteration steps completed." } } } } } ] }, "WorkflowStreamEventLoopStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "created_at": { "type": "integer", "format": "int64" }, "inputs": { "type": "object", "additionalProperties": true }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "metadata": { "type": "object", "additionalProperties": true }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "WorkflowStreamEventLoopNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer", "description": "Current loop iteration index (zero-based)." }, "created_at": { "type": "integer", "format": "int64" }, "pre_loop_output": { "description": "Output from the previous loop iteration.", "nullable": true }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "WorkflowStreamEventLoopCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "Whether the `outputs` data was truncated." }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Input variables for the loop." }, "inputs_truncated": { "type": "boolean", "description": "Whether the `inputs` data was truncated." }, "created_at": { "type": "integer", "format": "int64" }, "extras": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Additional metadata for the loop." }, "status": { "type": "string", "description": "Loop completion status." }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float" }, "total_tokens": { "type": "integer" }, "execution_metadata": { "type": "object", "additionalProperties": true, "description": "Execution metadata including token usage." }, "finished_at": { "type": "integer", "format": "int64" }, "steps": { "type": "integer", "description": "Number of loop iterations completed." } } } } } ] }, "WorkflowStreamEventHumanInputRequired": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "form_id": { "type": "string", "description": "Identifier for the form instance, surfaced in error messages and logs. Use `form_token` for Service API calls." }, "node_id": { "type": "string", "description": "ID of the Human Input node that produced this form." }, "node_title": { "type": "string", "description": "Display title of the Human Input node." }, "form_content": { "type": "string", "description": "Pre-rendered form body with workflow variables substituted." }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Form input control type. Available values: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads)." }, "output_variable_name": { "type": "string", "description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object." }, "default": { "type": "object", "nullable": true, "description": "Default value resolved from the workflow context. `null` when no default is configured.", "properties": { "type": { "type": "string", "description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable." }, "selector": { "type": "array", "items": { "type": "string" }, "description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements." }, "value": { "type": "string", "description": "Literal default value when `type` is `constant`. Always a string." } } } } }, "description": "Form input fields the recipient fills in." }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Identifier of the action button. Pass as `action` on [Submit Human Input Form](/en/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](/en/api-reference/human-input/get-human-input-form) and [Submit Human Input Form](/en/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 web app-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." } } } } } ] }, "WorkflowStreamEventWorkflowPaused": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid", "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/en/api-reference/workflow-runs/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." } } } } } ] }, "WorkflowStreamEventHumanInputFormFilled": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "ID of the Human Input node whose form was filled." }, "node_title": { "type": "string", "description": "Display title of the Human Input node." }, "rendered_content": { "type": "string", "description": "Form body rendered with the recipient's submitted values (`form_content` on `human_input_required` is the unfilled template)." }, "action_id": { "type": "string", "description": "Identifier of the action the recipient selected (matches the `action` value passed to [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form))." }, "action_text": { "type": "string", "description": "Display text of the selected action." }, "submitted_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Values the recipient submitted, keyed by each form input's `output_variable_name`." } } } } } ] }, "WorkflowStreamEventHumanInputFormTimeout": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "ID of the Human Input node whose form expired." }, "node_title": { "type": "string", "description": "Display title of the Human Input node." }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) when the form expired." } } } } } ] }, "WorkflowStreamEventAgentLog": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_execution_id": { "type": "string", "description": "Node execution ID." }, "id": { "type": "string", "description": "Agent log entry ID." }, "label": { "type": "string", "description": "Log label." }, "parent_id": { "type": "string", "nullable": true, "description": "Parent log entry ID." }, "error": { "type": "string", "nullable": true, "description": "Error message if the agent step failed." }, "status": { "type": "string", "description": "Agent step status." }, "data": { "type": "object", "additionalProperties": true, "description": "Agent step data." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Agent step metadata." }, "node_id": { "type": "string", "description": "Node ID." } } } } } ] }, "CompletionRequest": { "type": "object", "required": [ "inputs", "user" ], "properties": { "inputs": { "type": "object", "description": "Values for the app's input variables, keyed by variable name. The expected names and types come from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).", "additionalProperties": true }, "query": { "type": "string", "default": "", "description": "The text to process. Legacy field; newer apps pass this inside `inputs` instead." }, "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": "End-user identifier, defined by your app and unique within it. Messages and files are visible only to requests carrying the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity)." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, "description": "Files to attach to the request. For a local file, first upload it via [Upload File](/en/api-reference/files/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`." } } }, "CompletionResponse": { "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 the [Stop Completion Message Generation](/en/api-reference/completion-messages/stop-completion-message-generation) 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." }, "mode": { "type": "string", "description": "App mode, fixed as `completion`." }, "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)." } } }, "ChunkCompletionEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "message", "message_end", "message_file", "tts_message", "tts_message_end", "message_replace", "error", "ping" ], "description": "The type of streaming event." } }, "discriminator": { "propertyName": "event", "mapping": { "message": "#/components/schemas/StreamEventMessage", "message_end": "#/components/schemas/StreamEventMessageEnd", "message_file": "#/components/schemas/StreamEventMessageFile", "tts_message": "#/components/schemas/CompletionStreamEventTtsMessage", "tts_message_end": "#/components/schemas/CompletionStreamEventTtsMessageEnd", "message_replace": "#/components/schemas/StreamEventMessageReplace", "error": "#/components/schemas/CompletionStreamEventError", "ping": "#/components/schemas/CompletionStreamEventPing" } } }, "StreamEventMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "LLM returns text chunk event.", "properties": { "answer": { "type": "string", "description": "LLM returned text chunk content." } } } ] }, "StreamEventMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "Message end event, receiving this event means 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" } } } }, "files": { "type": "array", "nullable": true, "description": "Files generated during this message, such as model-generated images. `null` when no files were produced.", "items": { "type": "object", "properties": { "related_id": { "type": "string", "description": "ID of the message file record." }, "type": { "type": "string", "description": "File type, e.g. `image`." }, "filename": { "type": "string", "description": "File name." }, "extension": { "type": "string", "description": "File extension, including the leading dot, e.g. `.png`." }, "mime_type": { "type": "string", "description": "MIME type of the file." }, "size": { "type": "integer", "description": "File size in bytes." }, "transfer_method": { "type": "string", "description": "How the file is referenced: `remote_url`, `local_file`, or `tool_file`." }, "url": { "type": "string", "description": "Accessible URL of the file." }, "upload_file_id": { "type": "string", "description": "ID of the associated uploaded file." }, "remote_url": { "type": "string", "nullable": true, "description": "Original remote URL when the file was supplied as a remote URL; otherwise an empty string." } } } } } } ] }, "StreamEventMessageFile": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "type": "object", "description": "Message file event, a file (typically a model-generated image) produced during generation.", "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." } } } ] }, "StreamEventMessageReplace": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "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." } } } ] }, "CompletionStreamEventBase": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Task ID." }, "message_id": { "type": "string", "format": "uuid", "description": "Unique message ID." }, "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." } } }, "CompletionStreamEventTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "TTS audio stream event (base64 encoded MP3). Available if auto-play is 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." } } } ] }, "CompletionStreamEventTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "TTS audio stream end event.", "properties": { "audio": { "type": "string", "description": "Empty string. Signals the end of the audio stream." } } } ] }, "CompletionStreamEventError": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "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." } } } ] }, "CompletionStreamEventPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "type": "object", "description": "Ping event to keep connection alive. Delivered as an `event: ping` line with no `data:` payload." } ] }, "Dataset": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the knowledge base." }, "name": { "type": "string", "description": "Display name of the knowledge base. Unique within the workspace." }, "description": { "type": "string", "description": "Optional text describing the purpose or contents of the knowledge base." }, "provider": { "type": "string", "description": "Provider type. `vendor` for internally managed, `external` for external knowledge base connections." }, "permission": { "type": "string", "description": "Controls who can access this knowledge base. Possible values: `only_me`, `all_team_members`, `partial_members`." }, "data_source_type": { "type": "string", "description": "Data source type of the documents, `null` if not yet configured." }, "indexing_technique": { "type": "string", "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." }, "app_count": { "type": "integer", "description": "Number of applications currently using this knowledge base." }, "document_count": { "type": "integer", "description": "Total number of documents in the knowledge base." }, "word_count": { "type": "integer", "description": "Total word count across all documents." }, "created_by": { "type": "string", "description": "ID of the user who created the knowledge base." }, "author_name": { "type": "string", "description": "Display name of the creator." }, "created_at": { "type": "number", "description": "Creation timestamp (Unix epoch in seconds)." }, "updated_by": { "type": "string", "description": "ID of the user who last updated the knowledge base." }, "updated_at": { "type": "number", "description": "Last update timestamp (Unix epoch in seconds)." }, "embedding_model": { "type": "string", "description": "Name of the embedding model used for indexing." }, "embedding_model_provider": { "type": "string", "description": "Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). Legacy knowledge bases may return the bare short form (e.g. `openai`)." }, "embedding_available": { "type": "boolean", "description": "Whether the configured embedding model is currently available." }, "retrieval_model_dict": { "type": "object", "description": "Retrieval configuration for the knowledge base.", "properties": { "search_method": { "type": "string", "description": "Search method used for retrieval. `keyword_search` for keyword matching, `semantic_search` for embedding-based similarity, `full_text_search` for full-text indexing, `hybrid_search` for a combination of semantic and keyword approaches." }, "reranking_enable": { "type": "boolean", "description": "Whether reranking is enabled." }, "reranking_mode": { "type": "string", "nullable": true, "description": "Reranking mode. `reranking_model` for model-based reranking, `weighted_score` for score-based weighting. `null` if reranking is disabled." }, "reranking_model": { "type": "object", "description": "Reranking model configuration.", "properties": { "reranking_provider_name": { "type": "string", "description": "Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). Legacy knowledge bases may return the bare short form (e.g. `cohere`)." }, "reranking_model_name": { "type": "string", "description": "Name of the reranking model." } } }, "weights": { "type": "object", "nullable": true, "description": "Weight configuration for hybrid search.", "properties": { "weight_type": { "type": "string", "description": "Strategy for balancing semantic and keyword search weights." }, "vector_setting": { "type": "object", "description": "Semantic search weight settings.", "properties": { "vector_weight": { "type": "number", "description": "Weight assigned to semantic (vector) search results." }, "embedding_provider_name": { "type": "string", "description": "Provider of the embedding model used for vector search." }, "embedding_model_name": { "type": "string", "description": "Name of the embedding model used for vector search." } } }, "keyword_setting": { "type": "object", "description": "Keyword search weight settings.", "properties": { "keyword_weight": { "type": "number", "description": "Weight assigned to keyword search results." } } } } }, "top_k": { "type": "integer", "description": "Maximum number of results to return." }, "score_threshold_enabled": { "type": "boolean", "description": "Whether score threshold filtering is enabled." }, "score_threshold": { "type": "number", "description": "Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`." } } }, "summary_index_setting": { "type": "object", "nullable": true, "description": "Summary index configuration.", "properties": { "enable": { "type": "boolean", "description": "Whether summary indexing is enabled." }, "model_name": { "type": "string", "description": "Name of the model used for generating summaries." }, "model_provider_name": { "type": "string", "description": "Provider of the summary generation model." }, "summary_prompt": { "type": "string", "description": "Prompt template used for summary generation." } } }, "tags": { "type": "array", "description": "Tags associated with this knowledge base.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag identifier." }, "name": { "type": "string", "description": "Tag name." }, "type": { "type": "string", "description": "Tag type. Always `knowledge` for knowledge base tags." } } } }, "doc_form": { "type": "string", "description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction." }, "external_knowledge_info": { "type": "object", "nullable": true, "description": "Connection details for external knowledge bases. Present when `provider` is `external`.", "properties": { "external_knowledge_id": { "type": "string", "description": "ID of the external knowledge base." }, "external_knowledge_api_id": { "type": "string", "description": "ID of the external knowledge API connection." }, "external_knowledge_api_name": { "type": "string", "description": "Display name of the external knowledge API." }, "external_knowledge_api_endpoint": { "type": "string", "description": "Endpoint URL of the external knowledge API." } } }, "external_retrieval_model": { "type": "object", "nullable": true, "description": "Retrieval settings for external knowledge bases. `null` for internal knowledge bases.", "properties": { "top_k": { "type": "integer", "description": "Maximum number of results to return from the external knowledge base." }, "score_threshold": { "type": "number", "description": "Minimum similarity score threshold." }, "score_threshold_enabled": { "type": "boolean", "description": "Whether score threshold filtering is enabled." } } }, "doc_metadata": { "type": "array", "description": "Metadata field definitions for the knowledge base.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Metadata field identifier." }, "name": { "type": "string", "description": "Metadata field name." }, "type": { "type": "string", "description": "Metadata field value type." } } } }, "built_in_field_enabled": { "type": "boolean", "description": "Whether built-in metadata fields (e.g., `document_name`, `uploader`) are enabled." }, "pipeline_id": { "type": "string", "nullable": true, "description": "Pipeline ID, if a custom processing pipeline is configured." }, "runtime_mode": { "type": "string", "nullable": true, "description": "Runtime processing mode." }, "chunk_structure": { "type": "string", "nullable": true, "description": "Chunk structure configuration." }, "icon_info": { "type": "object", "nullable": true, "description": "Icon display configuration for the knowledge base.", "properties": { "icon_type": { "type": "string", "description": "Type of icon." }, "icon": { "type": "string", "description": "Icon identifier or emoji." }, "icon_background": { "type": "string", "description": "Background color for the icon." }, "icon_url": { "type": "string", "description": "URL of a custom icon image." } } }, "is_published": { "type": "boolean", "description": "Whether the knowledge base is published." }, "total_documents": { "type": "integer", "description": "Total number of documents." }, "total_available_documents": { "type": "integer", "description": "Number of documents that are enabled and available." }, "enable_api": { "type": "boolean", "description": "Whether API access is enabled for this knowledge base." }, "is_multimodal": { "type": "boolean", "description": "Whether multimodal content processing is enabled." }, "maintainer": { "type": "string", "nullable": true, "description": "Display name of the knowledge base maintainer. `null` if not set." }, "partial_member_list": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Account IDs of members granted access when `permission` is `partial_members`. Always present on the update response; on the detail response, present only when `permission` is `partial_members`." } } }, "Document": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the document." }, "position": { "type": "integer", "description": "Display position of the document in the list." }, "data_source_type": { "type": "string", "description": "How the document was created. `upload_file` for file uploads, `notion_import` for Notion imports." }, "data_source_info": { "type": "object", "description": "Raw data source information, varies by `data_source_type`." }, "data_source_detail_dict": { "type": "object", "description": "Detailed data source information including file details." }, "dataset_process_rule_id": { "type": "string", "description": "ID of the processing rule applied to this document." }, "name": { "type": "string", "description": "Document name." }, "created_from": { "type": "string", "description": "Origin of the document. `api` for API creation, `web` for UI creation." }, "created_by": { "type": "string", "description": "ID of the user who created the document." }, "created_at": { "type": "number", "description": "Creation timestamp (Unix epoch in seconds)." }, "tokens": { "type": "integer", "description": "Total number of tokens in the document." }, "indexing_status": { "type": "string", "description": "Current indexing status. `waiting` for queued, `parsing` while extracting content, `cleaning` while removing noise, `splitting` while chunking, `indexing` while building vectors, `completed` when ready, `error` if failed, `paused` if manually paused." }, "error": { "type": "string", "nullable": true, "description": "Error message if indexing failed. `null` when no error." }, "enabled": { "type": "boolean", "description": "Whether the document is enabled for retrieval." }, "disabled_at": { "type": "number", "nullable": true, "description": "Timestamp when the document was disabled. `null` if enabled." }, "disabled_by": { "type": "string", "nullable": true, "description": "ID of the user who disabled the document. `null` if enabled." }, "archived": { "type": "boolean", "description": "Whether the document is archived." }, "display_status": { "type": "string", "description": "User-facing display status derived from `indexing_status` and `enabled` state." }, "word_count": { "type": "integer", "description": "Total word count of the document." }, "hit_count": { "type": "integer", "description": "Number of times the document has been matched in retrieval queries." }, "doc_form": { "type": "string", "description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction." }, "doc_metadata": { "type": "array", "description": "Metadata values assigned to this document.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Metadata field identifier." }, "name": { "type": "string", "description": "Metadata field name." }, "type": { "type": "string", "description": "Metadata field value type." }, "value": { "type": "string", "description": "Metadata value for this document." } } } }, "summary_index_status": { "type": "string", "nullable": true, "description": "Status of the summary index for this document. `null` if summary indexing is not configured." }, "need_summary": { "type": "boolean", "description": "Whether a summary needs to be generated for this document." } } }, "Segment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the chunk." }, "position": { "type": "integer", "description": "Position of the chunk within the document." }, "document_id": { "type": "string", "description": "ID of the document this chunk belongs to." }, "content": { "type": "string", "description": "Text content of the chunk." }, "sign_content": { "type": "string", "description": "Signed content hash for integrity verification." }, "answer": { "type": "string", "description": "Answer content, used in Q&A mode documents." }, "word_count": { "type": "integer", "description": "Word count of the chunk content." }, "tokens": { "type": "integer", "description": "Token count of the chunk content." }, "keywords": { "type": "array", "description": "Keywords associated with this chunk for keyword-based retrieval.", "items": { "type": "string" } }, "index_node_id": { "type": "string", "description": "ID of the index node in the vector store." }, "index_node_hash": { "type": "string", "description": "Hash of the indexed content, used to detect changes." }, "hit_count": { "type": "integer", "description": "Number of times this chunk has been matched in retrieval queries." }, "enabled": { "type": "boolean", "description": "Whether the chunk is enabled for retrieval." }, "disabled_at": { "type": "number", "nullable": true, "description": "Timestamp when the chunk was disabled. `null` if enabled." }, "disabled_by": { "type": "string", "nullable": true, "description": "ID of the user who disabled the chunk. `null` if enabled." }, "status": { "type": "string", "description": "Current indexing status of the chunk, e.g. `completed`, `indexing`, `error`." }, "created_by": { "type": "string", "description": "ID of the user who created the chunk." }, "created_at": { "type": "number", "description": "Creation timestamp (Unix epoch in seconds)." }, "updated_at": { "type": "number", "description": "Last update timestamp (Unix epoch in seconds)." }, "updated_by": { "type": "string", "description": "ID of the user who last updated the chunk." }, "indexing_at": { "type": "number", "nullable": true, "description": "Timestamp when indexing started. `null` if not yet started." }, "completed_at": { "type": "number", "nullable": true, "description": "Timestamp when indexing completed. `null` if not yet completed." }, "error": { "type": "string", "nullable": true, "description": "Error message if indexing failed. `null` when no error." }, "stopped_at": { "type": "number", "nullable": true, "description": "Timestamp when indexing was stopped. `null` if not stopped." }, "child_chunks": { "type": "array", "description": "Child chunks belonging to this chunk. Only present for hierarchical mode documents.", "items": { "$ref": "#/components/schemas/ChildChunk" } }, "attachments": { "type": "array", "description": "Files attached to this chunk.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Attachment file identifier." }, "name": { "type": "string", "description": "Original file name." }, "size": { "type": "integer", "description": "File size in bytes." }, "extension": { "type": "string", "description": "File extension." }, "mime_type": { "type": "string", "description": "MIME type of the file." }, "source_url": { "type": "string", "description": "URL to access the attachment." } } } }, "summary": { "type": "string", "nullable": true, "description": "AI-generated summary of the chunk content. `null` if summary indexing is not enabled." } } }, "ChildChunk": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the child chunk." }, "segment_id": { "type": "string", "description": "ID of the parent chunk this child chunk belongs to." }, "content": { "type": "string", "description": "Text content of the child chunk." }, "position": { "type": "integer", "description": "Position of the child chunk within the parent chunk." }, "word_count": { "type": "integer", "description": "Word count of the child chunk content." }, "type": { "type": "string", "description": "How the child chunk was created. Child chunks created or updated through the API are always `customized`. System-generated child chunks are `automatic`." }, "created_at": { "type": "number", "description": "Creation timestamp (Unix epoch in seconds)." }, "updated_at": { "type": "number", "description": "Last update timestamp (Unix epoch in seconds)." } } }, "RetrievalModel": { "type": "object", "required": [ "search_method", "reranking_enable", "top_k", "score_threshold_enabled" ], "properties": { "search_method": { "type": "string", "description": "Search method used for retrieval.", "enum": [ "keyword_search", "semantic_search", "full_text_search", "hybrid_search" ] }, "reranking_enable": { "type": "boolean", "description": "Whether reranking is enabled." }, "reranking_model": { "type": "object", "description": "Reranking model configuration.", "properties": { "reranking_provider_name": { "type": "string", "description": "Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). A bare name like `cohere` expands to `langgenius//` and works only for langgenius-published plugins.\n\nGet valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=rerank`." }, "reranking_model_name": { "type": "string", "description": "Name of the reranking model." } } }, "reranking_mode": { "type": "string", "enum": [ "reranking_model", "weighted_score" ], "nullable": true, "description": "Reranking mode. Required when `reranking_enable` is `true`." }, "top_k": { "type": "integer", "description": "Maximum number of results to return." }, "score_threshold_enabled": { "type": "boolean", "description": "Whether score threshold filtering is enabled." }, "score_threshold": { "type": "number", "nullable": true, "description": "Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`." }, "weights": { "type": "object", "nullable": true, "description": "Weight configuration for hybrid search.", "properties": { "weight_type": { "type": "string", "description": "Strategy for balancing semantic and keyword search weights.", "enum": [ "semantic_first", "keyword_first", "customized" ] }, "vector_setting": { "type": "object", "description": "Semantic search weight settings.", "properties": { "vector_weight": { "type": "number", "description": "Weight assigned to semantic (vector) search results." }, "embedding_provider_name": { "type": "string", "description": "Provider of the embedding model used for vector search." }, "embedding_model_name": { "type": "string", "description": "Name of the embedding model used for vector search." } } }, "keyword_setting": { "type": "object", "description": "Keyword search weight settings.", "properties": { "keyword_weight": { "type": "number", "description": "Weight assigned to keyword search results." } } } } }, "metadata_filtering_conditions": { "type": "object", "nullable": true, "description": "Restrict retrieval to chunks whose document metadata matches the given conditions. Conditions are evaluated server-side against document metadata fields.", "properties": { "logical_operator": { "type": "string", "enum": [ "and", "or" ], "default": "and", "nullable": true, "description": "How to combine multiple conditions." }, "conditions": { "type": "array", "nullable": true, "description": "List of metadata conditions to evaluate.", "items": { "type": "object", "required": [ "name", "comparison_operator" ], "properties": { "name": { "type": "string", "description": "Metadata field name to compare against." }, "comparison_operator": { "type": "string", "description": "Comparison to apply, by metadata type:\n\n- String or array metadata: `contains`, `not contains`, `start with`, `end with`, `is`, `is not`, `empty`, `not empty`, `in`, `not in`\n- Numeric metadata: `=`, `≠`, `>`, `<`, `≥`, `≤`\n- Time metadata: `before`, `after`", "enum": [ "contains", "not contains", "start with", "end with", "is", "is not", "empty", "not empty", "in", "not in", "=", "≠", ">", "<", "≥", "≤", "before", "after" ] }, "value": { "nullable": true, "description": "Value to compare against. Type depends on `comparison_operator`: string for most string operators, array of strings for `in` and `not in`, number for numeric operators, and omitted for `empty` and `not empty`.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" } ] } } } } } } } } } } }