{ "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, New Agent, Chatbot, 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 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- **Agent**: `agent_thought` reasoning and tool-call steps alongside `agent_message` chunks → `message_end`.\n- **New 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, New Agent | each answer chunk (concatenate in order); for New Agent, one closing chunk with the complete answer | `answer` |\n| `agent_message` | Agent, New Agent | each answer chunk (concatenate in order) | `answer` |\n| `agent_thought` | Agent, New 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, 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, 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 every 10 seconds | none |" }, "examples": { "streamingResponseBasic": { "summary": "Response Example - Streaming (Basic)", "value": "data: {\"event\": \"message\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"created_at\": 1679586595, \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" }, "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} data: {\"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} data: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333} data: {\"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": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"The user greeted me, so\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395335, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}" }, "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"paused_nodes\": [\"approval_node\"], \"outputs\": {}, \"reasons\": [{\"TYPE\": \"human_input_required\", \"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"resolved_default_values\": {\"comment\": \"\"}, \"form_token\": \"tok_abc123\", \"expiration_time\": 1705494029}], \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5, \"total_tokens\": 0, \"total_steps\": 1}}" } } } } }, "400": { "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `not_chat_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.\n- `bad_request` : Cannot use draft workflow version.\n- `bad_request` : Invalid `workflow_id` format.\n- `bad_request` : `blocking` response mode with a New Agent app.\n- `invalid_param` : The New Agent app has no bound Agent.\n- `agent_not_published` : The bound Agent has no published version. (New 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, New Agent, Chatbot, 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, New Agent, Chatbot, 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, New Agent, Chatbot, 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, 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, New Agent, Chatbot, 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, 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, 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, New Agent, Chatbot, 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, New Agent, Chatbot, 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, 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, New Agent, Chatbot, 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, 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, New Agent, Chatbot, 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, New Agent, Chatbot, Agent, Text Generator apps.\n\nTranscribes an uploaded audio file to text using the app's configured 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": "- `app_unavailable` : The app is unavailable or misconfigured.\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- `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 speech recognition request failed.", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "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." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "413": { "description": "`audio_too_large` : 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, New Agent, Chatbot, 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 file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). When the configured TTS provider returns a stream, the audio is delivered as `audio/mpeg` with chunked transfer encoding; the request `streaming` field does not control this.", "content": { "audio/mpeg": { "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, New Agent, Chatbot, 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, New Agent, Chatbot, 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. (New 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, New Agent, Chatbot, 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, New Agent, Chatbot, Agent, Text Generator apps.\n\nReturns the branding and display settings for the app's hosted WebApp, such as its title, icon, theme colors, and default language.", "operationId": "getChatWebAppSettings", "tags": [ "Applications" ], "responses": { "200": { "description": "WebApp settings of the application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" }, "examples": { "webAppSettings": { "summary": "Response Example", "value": { "title": "My Chat App", "chat_color_theme": "#4A90D9", "chat_color_theme_inverted": false, "icon_type": "emoji", "icon": "🤖", "icon_background": "#FFFFFF", "icon_url": null, "description": "A helpful customer service chatbot.", "copyright": "2025 Dify", "privacy_policy": "https://example.com/privacy", "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, 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, 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, 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, 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, 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, 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 WebApp 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 WebApp delivery.", "operationId": "submitChatflowHumanInputForm", "parameters": [ { "name": "form_token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Access token for the paused form, returned in the `human_input_required` event from the Run Workflow or Send Chat Message endpoint in streaming mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs", "action", "user" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "Submitted values keyed by each input's `output_variable_name`. Paragraph and select inputs take a string; a `file` input takes one file mapping; a `file-list` input takes an array of file mappings.\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 WebApp 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. Each event is delivered as `data: {JSON}\\n\\n`. Event payloads follow the same schemas as the original streaming response.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE stream of events from a resumed workflow run, in the same format as [Run Workflow](/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": "data: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\", \"submitted_data\": {\"comment\": \"Looks good.\"}}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_2\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Approved, now translating.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour\"}, \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}" }, "resumedRunChatflow": { "summary": "Response Example - Resumed run (Chatflow)", "value": "data: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\", \"submitted_data\": {\"comment\": \"Looks good.\"}}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"The reviewer approved the draft.\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"answer\": \"Approved\", \"created_at\": 1705407706} data: {\"event\": \"node_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"status\": \"succeeded\", \"elapsed_time\": 1.2, \"created_at\": 1705407705, \"finished_at\": 1705407706}} data: {\"event\": \"message_end\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"metadata\": {\"usage\": {\"total_tokens\": 42, \"latency\": 1.3}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}" } } } } }, "400": { "description": "`not_workflow_app` : Please check if your app mode matches the right API route.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : Workflow run not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow run not found" } } } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Resume stream", "source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}' \\\n --header 'Authorization: Bearer {api_key}'" }, { "lang": "bash", "label": "With state snapshot", "source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}&include_state_snapshot=true' \\\n --header 'Authorization: Bearer {api_key}'" } ], "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 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": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" }, "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : 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 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": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" }, "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : 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." } } } } } } }, "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." }, "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." } } } } } } }, "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." }, "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." } } } } } } }, "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." } } } } } } }, "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." }, "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." } } } } } } }, "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." } } } } } } }, "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." } } } } } } }, "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." } } } } } } }, "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." } } } } } } }, "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` : A referenced document was not found, or another metadata operation is already running for a document in this request.", "content": { "application/json": { "examples": { "invalid_param_doc": { "summary": "invalid_param (document)", "value": { "status": 400, "code": "invalid_param", "message": "Document not found." } } } } } }, "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-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." } } } } } }, "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- Agent and New 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`. New 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 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." } ] }, "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`, `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 generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for Chatflow apps, `workflow` for Workflow apps, `agent` for New 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": "WebApp title." }, "chat_color_theme": { "type": "string", "description": "Chat color theme." }, "chat_color_theme_inverted": { "type": "boolean", "description": "Whether the chat color theme is inverted." }, "icon_type": { "type": "string", "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." }, "icon": { "type": "string", "description": "Icon content (emoji or image ID)." }, "icon_background": { "type": "string", "description": "Icon background color." }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "URL of the icon image." }, "description": { "type": "string", "description": "WebApp description." }, "copyright": { "type": "string", "description": "Copyright text." }, "privacy_policy": { "type": "string", "description": "Privacy policy URL." }, "input_placeholder": { "type": "string", "nullable": true, "description": "Placeholder text shown in the WebApp 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 WebApp-delivered forms)." }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Pre-filled default values for the form inputs, keyed by input `output_variable_name`. All values are stringified." }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) after which the form can no longer be submitted." } } } } } ] }, "StreamEventWorkflowPaused": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/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 a plugin trigger." } } }, "EndUserSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "End user ID." }, "type": { "type": "string", "description": "End user type." }, "is_anonymous": { "type": "boolean", "description": "Whether the end user is anonymous." }, "session_id": { "type": "string", "description": "Session identifier." } } }, "HumanInputContent": { "type": "object", "description": "Execution content from a Human Input node, including form definition and submission data.", "properties": { "workflow_run_id": { "type": "string", "description": "ID of the workflow run this content belongs to." }, "submitted": { "type": "boolean", "description": "Whether the human input form has been submitted." }, "type": { "type": "string", "description": "`human_input` for human input content." }, "form_definition": { "nullable": true, "description": "Form definition from the Human Input node. `null` when the content represents a submission response.", "$ref": "#/components/schemas/HumanInputFormDefinition" }, "form_submission_data": { "nullable": true, "description": "Submitted form data. `null` when the form has not been submitted yet.", "$ref": "#/components/schemas/HumanInputFormSubmissionData" } } }, "HumanInputFormDefinition": { "type": "object", "description": "Definition of a human input form rendered by a Human Input node.", "properties": { "form_id": { "type": "string", "description": "Unique form identifier." }, "node_id": { "type": "string", "description": "ID of the Human Input node that generated this form." }, "node_title": { "type": "string", "description": "Title of the Human Input node." }, "form_content": { "type": "string", "description": "Markdown or text content displayed with the form." }, "inputs": { "type": "array", "description": "Input fields in the form.", "items": { "$ref": "#/components/schemas/FormInput" } }, "actions": { "type": "array", "description": "Action buttons available on the form.", "items": { "$ref": "#/components/schemas/UserAction" } }, "display_in_ui": { "type": "boolean", "description": "Whether the form should be displayed in the UI." }, "form_token": { "type": "string", "nullable": true, "description": "Token for form submission authentication." }, "resolved_default_values": { "type": "object", "additionalProperties": true, "description": "Resolved default values for form inputs, keyed by output variable name." }, "expiration_time": { "type": "integer", "description": "Unix timestamp when the form expires." } } }, "HumanInputFormSubmissionData": { "type": "object", "description": "Data from a submitted human input form.", "properties": { "node_id": { "type": "string", "description": "ID of the Human Input node." }, "node_title": { "type": "string", "description": "Title of the Human Input node." }, "rendered_content": { "type": "string", "description": "Rendered content of the form submission." }, "action_id": { "type": "string", "description": "ID of the action button that was clicked." }, "action_text": { "type": "string", "description": "Display text of the action button that was clicked." } } }, "FormInput": { "type": "object", "description": "A form input field definition.", "properties": { "type": { "type": "string", "description": "Form input control type. Available values: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads)." }, "output_variable_name": { "type": "string", "description": "Variable name where the input value is stored." }, "default": { "nullable": true, "description": "Default value configuration for this input.", "$ref": "#/components/schemas/FormInputDefault" } } }, "FormInputDefault": { "type": "object", "description": "Default value configuration for a form input.", "properties": { "type": { "type": "string", "description": "`variable` for dynamic values from workflow variables, `constant` for static values." }, "selector": { "type": "array", "items": { "type": "string" }, "description": "Variable selector path when `type` is `variable`." }, "value": { "type": "string", "description": "Static value when `type` is `constant`." } } }, "UserAction": { "type": "object", "description": "An action button on a human input form.", "properties": { "id": { "type": "string", "description": "Unique action identifier." }, "title": { "type": "string", "description": "Button display text." }, "button_style": { "type": "string", "description": "`primary`, `default`, `accent`, or `ghost`." } } }, "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. No additional properties." } ] }, "WorkflowFinishedData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Workflow run ID." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Workflow ID." }, "status": { "type": "string", "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output data from the workflow." }, "error": { "type": "string", "nullable": true, "description": "Error message if the workflow failed." }, "elapsed_time": { "type": "number", "format": "float", "description": "Total time elapsed in seconds." }, "total_tokens": { "type": "integer", "description": "Total tokens consumed across all nodes." }, "total_steps": { "type": "integer", "description": "Total number of workflow steps executed." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp of when the workflow run was created." }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp of when the workflow run finished." }, "created_by": { "type": "object", "additionalProperties": true, "description": "Creator information. Only present in streaming `workflow_finished` events." }, "exceptions_count": { "type": "integer", "nullable": true, "description": "Number of exceptions encountered during execution. Only present in streaming `workflow_finished` events." }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true, "description": "Files generated during workflow execution. Only present in streaming `workflow_finished` events." } } }, "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 WebApp-delivered forms)." }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Pre-filled default values for the form inputs, keyed by input `output_variable_name`. All values are stringified." }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix timestamp (seconds) after which the form can no longer be submitted." } } } } } ] }, "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." } ] }, "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" } ] } } } } } } } } } } }