{ "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\nSend a request to the chat application. Works with Chatbot, Agent, Chatflow, and New Agent apps; 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 (SSE).\n\n**Parsing**: Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing the JSON, then read the `event` field to determine the event type. Ignore `ping` events, which arrive as `event: ping` lines (no `data:` payload) every 10 seconds to keep the connection alive.\n\n**Stream lifecycle**: For Chatbot apps, the reply streams as `message` events; for Agent apps, as `agent_thought` and `agent_message` events. The stream ends with `message_end`; when text-to-speech auto-play is enabled, `tts_message` events interleave and `tts_message_end` becomes the final event.\n\nFor Chatflow apps, workflow progress streams as `workflow_started`, node events (`node_started` and `node_finished`, plus iteration and loop variants), and the reply as `message` events (an LLM node with `reasoning_format: separated` also emits `reasoning_chunk` events alongside, carrying the model's reasoning content). When text-to-speech auto-play is enabled, `tts_message_end` trails the closing event. The closing sequence depends on the outcome:\n- **Success**: `message_end`, then `workflow_finished`\n- **Failure**: `workflow_finished` with status `failed`, then `error`; no `message_end`\n- **Pause**: `human_input_required`, then `workflow_paused` (the stream ends here; the run resumes separately)\n\nFor New Agent apps, the reply streams incrementally as `agent_message` events, with the model's reasoning and tool calls streaming alongside as `agent_thought` events; a single closing `message` event then carries the complete answer (render the deltas live and treat that `message` as the final answer rather than appending it). `message_end` metadata carries `usage` (plus `annotation_reply` when an annotation match replies) and never includes `retriever_resources`.\n\n**Events**: Apart from `ping`, every event includes `conversation_id`, `message_id`, and `created_at` (Unix epoch seconds); all but `error` also include `task_id`. Workflow, node, and human-input events (Chatflow apps) also nest their payload under `data` and, except for `agent_log`, carry a top-level `workflow_run_id`.\n\n**Reply events**\n\n| Event | 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)", "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 } } } } } }, "404": { "description": "- `not_found` : Conversation does not exist.\n- `not_found` : Workflow not found with the specified `workflow_id`.", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } }, "workflow_not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab" } } } } } }, "429": { "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal server error." } } } } } } }, "x-mint": { "href": "/en/api-reference/chat-messages/send-chat-message", "metadata": { "title": "Send Chat Message", "sidebarTitle": "Send Chat Message" } } } }, "/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, can be obtained from the streaming chunk return of the [Send Chat Message](/en/api-reference/chat-messages/send-chat-message) API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "User identifier. Must match the `user` passed when the message was sent: if it differs, the stop silently does nothing and the response still returns success." } } }, "examples": { "example": { "summary": "Request Example", "value": { "user": "abc-123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } } } } } } }, "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, Chatbot, Agent apps.\n\nGet next questions suggestions for the current message.", "operationId": "getSuggestedQuestions", "tags": [ "Chat Messages" ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "Message ID.", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": true, "description": "User identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved suggested questions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponse" }, "examples": { "suggestedQuestions": { "summary": "Response Example", "value": { "result": "success", "data": [ "What colors does the iPhone 13 Pro Max come in?", "How does the battery compare to iPhone 12?", "What is the price range?" ] } } } } } }, "400": { "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Suggested questions feature is disabled.", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } }, "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Suggested Questions Is Disabled." } } } } } }, "404": { "description": "`not_found` : Message does not exist.", "content": { "application/json": { "examples": { "message_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Message Not Exists." } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal server error." } } } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://{api_base_url}/messages/{message_id}/suggested?user={user}' \\\n --header 'Authorization: Bearer {api_key}'" } ], "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\nUpload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", "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 be uploaded. Supported types include images, documents, audio, and video." }, "user": { "type": "string", "description": "Identifier for the end user, defined by your application's rules and unique within the app. Service API and WebApp user IDs are separate, even when identical. If omitted, the upload is attributed to the shared `DEFAULT-USER` end user; a file can only be used later by requests carrying the same `user` value." } } } } } }, "responses": { "201": { "description": "File uploaded successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" }, "examples": { "uploadSuccess": { "summary": "Response Example", "value": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "name": "product-photo.png", "size": 204800, "extension": "png", "mime_type": "image/png", "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "created_at": 1705407629, "preview_url": null, "source_url": "https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI=", "original_url": null, "user_id": null, "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "conversation_id": null, "file_key": null } } } } } }, "400": { "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `invalid_param` : The filename contains invalid characters (`/` or `\\`).", "content": { "application/json": { "examples": { "no_file_uploaded": { "summary": "no_file_uploaded", "value": { "status": 400, "code": "no_file_uploaded", "message": "Please upload your file." } }, "too_many_files": { "summary": "too_many_files", "value": { "status": 400, "code": "too_many_files", "message": "Only one file is allowed." } }, "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "status": 400, "code": "filename_not_exists_error", "message": "The specified filename does not exist." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Filename contains invalid characters" } } } } } }, "413": { "description": "`file_too_large` : File size exceeded.", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "File size exceeded." } } } } } }, "415": { "description": "`unsupported_file_type` : File type not allowed.", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "x-mint": { "href": "/en/api-reference/files/upload-file", "metadata": { "title": "Upload File", "sidebarTitle": "Upload File" } } } }, "/files/{file_id}/preview": { "get": { "summary": "Download File", "description": "**Available for**: Chatflow, Chatbot, Agent, Text Generator apps.\n\nPreview or download uploaded files previously uploaded via the [Upload File](/en/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", "operationId": "previewChatFile", "tags": [ "Files" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The unique identifier of the file to preview, obtained from the [Upload File](/en/api-reference/files/upload-file) API response.", "schema": { "type": "string", "format": "uuid" } }, { "name": "as_attachment", "in": "query", "required": false, "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", "schema": { "type": "boolean", "default": false } }, { "name": "user", "in": "query", "required": false, "description": "User identifier, used for end-user context.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "`file_access_denied` : Access to the requested file is denied.", "content": { "application/json": { "examples": { "file_access_denied": { "summary": "file_access_denied", "value": { "status": 403, "code": "file_access_denied", "message": "Access to the requested file is denied." } } } } } }, "404": { "description": "`file_not_found` : The requested file was not found.", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "status": 404, "code": "file_not_found", "message": "The requested file was not found." } } } } } } }, "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, Chatbot, Agent, Text Generator apps.\n\nRetrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/en/api-reference/files/upload-file)).", "operationId": "getEndUserChat", "tags": [ "End Users" ], "parameters": [ { "name": "end_user_id", "in": "path", "required": true, "description": "End user ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "End user retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserDetail" }, "examples": { "endUserDetail": { "summary": "Response Example", "value": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "type": "service_api", "external_user_id": "abc-123", "name": null, "is_anonymous": false, "session_id": "abc-123", "created_at": "2024-01-16T12:00:29Z", "updated_at": "2024-01-16T12:00:29Z" } } } } } }, "404": { "description": "`end_user_not_found` : End user not found.", "content": { "application/json": { "examples": { "end_user_not_found": { "summary": "end_user_not_found", "value": { "status": 404, "code": "end_user_not_found", "message": "End user not found." } } } } } } }, "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\nSubmit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.", "operationId": "postChatMessageFeedback", "tags": [ "Feedback" ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "Message ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFeedbackRequest" }, "examples": { "likeFeedback": { "summary": "Request Example", "value": { "rating": "like", "user": "abc-123", "content": "This answer was very helpful!" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "404": { "description": "`not_found` : Message does not exist.", "content": { "application/json": { "examples": { "message_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Message Not Exists." } } } } } } }, "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\nRetrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.", "operationId": "getChatAppFeedbacks", "tags": [ "Feedback" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Number of records per page.", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 101 } } ], "responses": { "200": { "description": "A list of application feedbacks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppFeedbacksResponse" }, "examples": { "feedbacksList": { "summary": "Response Example", "value": { "data": [ { "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "rating": "like", "content": "The response accurately answered my question about product specifications.", "from_source": "user", "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "from_account_id": null, "created_at": "2025-01-16T14:30:29Z", "updated_at": "2025-01-16T14:30:29Z" }, { "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", "rating": "dislike", "content": "The answer was too vague and did not address the specific pricing question.", "from_source": "user", "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", "from_account_id": null, "created_at": "2025-01-15T09:12:45Z", "updated_at": "2025-01-15T09:12:45Z" } ] } } } } } } }, "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\nRetrieve the conversation list for the current user, ordered by most recently active.", "operationId": "getConversationsList", "tags": [ "Conversations" ], "parameters": [ { "name": "user", "in": "query", "required": false, "description": "User identifier.", "schema": { "type": "string" } }, { "name": "last_id", "in": "query", "required": false, "description": "The ID of the last record on the current page (for pagination).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of records to return.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "sort_by", "in": "query", "required": false, "description": "Sorting field. Use '-' prefix for descending order.", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-updated_at" } } ], "responses": { "200": { "description": "Successfully retrieved conversations list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsListResponse" }, "examples": { "conversationsList": { "summary": "Response Example", "value": { "limit": 20, "has_more": false, "data": [ { "id": "45701982-8118-4bc5-8e9b-64562b4555f2", "name": "iPhone Specs Chat", "inputs": { "city": "San Francisco" }, "status": "normal", "introduction": "Welcome! How can I help you today?", "created_at": 1705407629, "updated_at": 1705411229 } ] } } } } } }, "400": { "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : Last conversation does not exist (invalid `last_id`).", "content": { "application/json": { "examples": { "last_conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Last Conversation Not Exists." } } } } } } }, "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 historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order.", "operationId": "getConversationHistory", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "query", "required": true, "description": "Conversation ID.", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "User identifier.", "schema": { "type": "string" } }, { "name": "first_id", "in": "query", "required": false, "description": "The ID of the first chat record on the current page. Default is `null` (fetches the latest messages). For subsequent pages, use the ID of the first message from the current list to get older messages.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of chat history messages to return per request.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Successfully retrieved conversation history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationHistoryResponse" }, "examples": { "conversationHistory": { "summary": "Response Example", "value": { "limit": 20, "has_more": false, "data": [ { "id": "9da23599-e713-473b-982c-4328d4f5c78a", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "parent_message_id": null, "inputs": { "city": "San Francisco" }, "query": "What are the specs of the iPhone 13 Pro Max?", "answer": "iPhone 13 Pro Max specs are listed here:...", "status": "normal", "error": null, "message_files": [], "feedback": { "rating": "like" }, "retriever_resources": [], "agent_thoughts": [], "created_at": 1705407629, "extra_contents": [] } ] } } } } } }, "400": { "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "- `not_found` : Conversation does not exist.\n- `not_found` : First message does not exist.", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } }, "first_message_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "First Message Not Exists." } } } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://{api_base_url}/messages?conversation_id={conversation_id}&user={user}' \\\n --header 'Authorization: Bearer {api_key}'" } ], "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\nRetrieve variables from a specific conversation.", "operationId": "getConversationVariables", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID.", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "The user identifier.", "schema": { "type": "string" } }, { "name": "last_id", "in": "query", "required": false, "description": "The ID of the last record on the current page (for pagination).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of records to return.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "variable_name", "in": "query", "required": false, "description": "Filter variables by a specific name.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Successfully retrieved conversation variables.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariablesResponse" }, "examples": { "conversationVariables": { "summary": "Response Example", "value": { "limit": 20, "has_more": false, "data": [ { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "name": "user_preference", "value_type": "string", "value": "dark_mode", "description": "User preference setting", "created_at": 1705407629, "updated_at": 1705411229 } ] } } } } } }, "400": { "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : Conversation does not exist.", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } } } } } } }, "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, Chatbot, Agent apps.\n\nRename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations.", "operationId": "renameConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequest" }, "examples": { "renameExample": { "summary": "Request Example", "value": { "name": "iPhone Specs Chat", "user": "abc-123" } } } } } }, "responses": { "200": { "description": "Conversation renamed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationListItem" }, "examples": { "renamedConversation": { "summary": "Response Example", "value": { "id": "45701982-8118-4bc5-8e9b-64562b4555f2", "name": "iPhone Specs Chat", "inputs": { "city": "San Francisco" }, "status": "normal", "introduction": "Welcome! How can I help you today?", "created_at": 1705407629, "updated_at": 1705411229 } } } } } }, "400": { "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : Conversation does not exist.", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } } } } } } }, "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\nUpdate the value of a specific conversation variable. The value must match the expected type.", "operationId": "updateChatConversationVariable", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "variable_id", "in": "path", "required": true, "description": "Variable ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariableUpdateRequest" }, "examples": { "updateStringVariable": { "summary": "Request Example", "value": { "value": "new value", "user": "abc-123" } } } } } }, "responses": { "200": { "description": "Variable updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariableItem" }, "examples": { "updatedVariable": { "summary": "Response Example", "value": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "name": "user_preference", "value_type": "string", "value": "new value", "description": "User preference setting", "created_at": 1705407629, "updated_at": 1705411229 } } } } } }, "400": { "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Variable value type mismatch.", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } }, "type_mismatch": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Value type mismatch: expected string, got integer." } } } } } }, "404": { "description": "- `not_found` : Conversation does not exist.\n- `not_found` : Conversation variable does not exist.", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } }, "variable_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Variable Not Exists." } } } } } } }, "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, Chatbot, Agent apps.\n\nDelete a conversation.", "operationId": "deleteConversation", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID.", "schema": { "type": "string" } } ], "requestBody": { "description": "A JSON body is always required, even when `user` is omitted; send `{}` in that case.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "The user identifier." } } }, "examples": { "deleteExample": { "value": { "user": "abc-123" }, "summary": "Request Example" } } } } }, "responses": { "204": { "description": "Conversation deleted successfully. No content returned." }, "400": { "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : Conversation does not exist.", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } } } } } } }, "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, Chatbot, Agent, Text Generator apps.\n\nConvert audio file to text. The uploaded file's MIME type must be one of `audio/mp3`, `audio/m4a`, `audio/wav`, `audio/amr`, `audio/mpga`; other types, including the common `audio/mpeg`, are rejected with the `unsupported_audio_type` error. File size limit is `30 MB`.", "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` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "no_audio_uploaded": { "summary": "no_audio_uploaded", "value": { "status": 400, "code": "no_audio_uploaded", "message": "Please upload your audio." } }, "provider_not_support_speech_to_text": { "summary": "provider_not_support_speech_to_text", "value": { "status": 400, "code": "provider_not_support_speech_to_text", "message": "Provider not support speech to text." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "413": { "description": "`audio_too_large` : Audio file size exceeded the limit.", "content": { "application/json": { "examples": { "audio_too_large": { "summary": "audio_too_large", "value": { "status": 413, "code": "audio_too_large", "message": "Audio size exceeded." } } } } } }, "415": { "description": "`unsupported_audio_type` : Audio type is not allowed.", "content": { "application/json": { "examples": { "unsupported_audio_type": { "summary": "unsupported_audio_type", "value": { "status": 415, "code": "unsupported_audio_type", "message": "Audio type not allowed." } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal server error." } } } } } } }, "x-mint": { "href": "/en/api-reference/audio/convert-audio-to-text", "metadata": { "title": "Convert Audio to Text", "sidebarTitle": "Convert Audio to Text" } } } }, "/text-to-audio": { "post": { "summary": "Convert Text to Audio", "description": "**Available for**: Chatflow, Workflow, Chatbot, Agent, Text Generator apps.\n\nConvert text to speech.", "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`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal server error." } } } } } } }, "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\nRetrieve basic information about this application, including name, description, tags, and mode.", "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\nRetrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.", "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` : App unavailable or misconfigured.\n- `agent_not_published` : The bound Agent has no published version. (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\nRetrieve metadata about this application, including tool icons and other configuration details.", "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, Chatbot, Agent, Text Generator apps.\n\nRetrieve the WebApp settings of this application, including site configuration, theme, and customization options.", "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", "custom_disclaimer": "", "default_language": "en-US", "show_workflow_steps": false, "use_icon_as_answer_icon": true } } } } } }, "403": { "description": "`forbidden` : Site not found for this application or the workspace has been archived.", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden", "value": { "status": 403, "code": "forbidden", "message": "Forbidden." } } } } } } }, "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 a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a 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\nRetrieves a paginated list of annotations for the application. Supports keyword search filtering.", "operationId": "getAnnotationList", "tags": [ "Annotations" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination.", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of items per page.", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "keyword", "in": "query", "description": "Keyword to filter annotations by question or answer content.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved annotation list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationListResponse" }, "examples": { "annotationList": { "summary": "Response Example", "value": { "data": [ { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "question": "What is Dify?", "answer": "Dify is an open-source LLM application development platform.", "hit_count": 5, "created_at": 1705407629 } ], "has_more": false, "limit": 20, "total": 1, "page": 1 } } } } } } }, "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 the question and answer of an existing annotation.", "operationId": "updateAnnotation", "tags": [ "Annotations" ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "description": "The unique identifier of the annotation to update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" }, "examples": { "updateAnnotation": { "summary": "Request Example", "value": { "question": "What is Dify?", "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." } } } } } }, "responses": { "200": { "description": "Annotation updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" }, "examples": { "updatedAnnotation": { "summary": "Response Example", "value": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "question": "What is Dify?", "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", "hit_count": 5, "created_at": 1705407629 } } } } } }, "404": { "description": "`not_found` : Annotation does not exist.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Annotation not found." } } } } } } }, "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": "The unique identifier of the annotation to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Annotation deleted successfully." }, "404": { "description": "`not_found` : Annotation does not exist.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Annotation not found." } } } } } } }, "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 the annotation reply feature. The request body is validated before the action runs, so `embedding_provider_name`, `embedding_model_name`, and `score_threshold` are required for both `enable` and `disable`. Executes asynchronously; use [Get Annotation Reply Job Status](/en/api-reference/annotations/get-annotation-reply-job-status) to track progress.", "operationId": "initialAnnotationReplySettings", "tags": [ "Annotations" ], "parameters": [ { "name": "action", "in": "path", "required": true, "description": "Action to perform.", "schema": { "type": "string", "enum": [ "enable", "disable" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" }, "examples": { "enableAnnotationReply": { "summary": "Request Example", "value": { "score_threshold": 0.9, "embedding_provider_name": "openai", "embedding_model_name": "text-embedding-3-small" } } } } } }, "responses": { "200": { "description": "Annotation reply settings task initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" }, "examples": { "annotationReplyResponse": { "summary": "Response Example", "value": { "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "job_status": "waiting" } } } } } } }, "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\nRetrieves the status of an asynchronous 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\nRetrieve the current execution results of a workflow task based on the workflow execution ID.", "operationId": "getWorkflowRunDetail", "tags": [ "Workflow Runs" ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "description": "Workflow run ID, can be obtained from the workflow execution response, streaming events, or message metadata.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved workflow run details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponse" }, "examples": { "workflowRunDetail": { "summary": "Response Example", "value": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "inputs": "{\"query\": \"Translate this to French\"}", "outputs": { "result": "Traduisez ceci en francais" }, "error": null, "total_steps": 3, "total_tokens": 150, "created_at": 1705407629, "finished_at": 1705407630, "elapsed_time": 1.23 } } } } } }, "400": { "description": "`not_workflow_app` : App mode does not match the API route.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : Workflow run not found.", "content": { "application/json": { "examples": { "workflow_run_not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow run not found." } } } } } } }, "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 for pagination.", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 99999 } }, { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "created_at__before", "in": "query", "description": "Filter logs created before this ISO 8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at__after", "in": "query", "description": "Filter logs created after this ISO 8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_by_end_user_session_id", "in": "query", "description": "Filter by end user session ID.", "schema": { "type": "string" } }, { "name": "created_by_account", "in": "query", "description": "Filter by the creator's account email (e.g., `name@example.com`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved workflow logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponse" }, "examples": { "workflowLogs": { "summary": "Response Example", "value": { "page": 1, "limit": 20, "total": 1, "has_more": false, "data": [ { "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", "workflow_run": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "version": "2025-01-16 12:00:00.000000", "status": "succeeded", "error": null, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630, "exceptions_count": 0, "triggered_from": "app-run" }, "created_from": "service-api", "created_by_role": "end_user", "created_by_account": null, "created_by_end_user": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "type": "service_api", "is_anonymous": false, "session_id": "user_workflow_123" }, "created_at": 1705407629 } ] } } } } } } }, "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\nRetrieve a paused Human Input form's contents. Requires WebApp delivery.\n\nSee the [API Integration Flow](/en/api-reference/guides/human-input-flow) for the end-to-end sequence of calling Human Input endpoints.", "operationId": "getChatflowHumanInputForm", "parameters": [ { "name": "form_token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Access token for the paused form, returned in the `human_input_required` event from the Run Workflow or Send Chat Message endpoint in streaming mode." } ], "responses": { "200": { "description": "Form contents retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "form_content": { "type": "string", "description": "Pre-rendered form body with workflow variables substituted." }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Form input control type. Available values: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads)." }, "output_variable_name": { "type": "string", "description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object." }, "default": { "type": "object", "nullable": true, "description": "Raw default-value configuration for `paragraph` inputs. The client should not resolve this directly; use `resolved_default_values` to display defaults. `null` for other input types or when no default is configured.", "properties": { "type": { "type": "string", "description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable." }, "selector": { "type": "array", "items": { "type": "string" }, "description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements." }, "value": { "type": "string", "description": "Literal default value when `type` is `constant`. Always a string." } } }, "option_source": { "type": "object", "description": "Source of options for `select` inputs. Present only when `type` is `select`.", "properties": { "type": { "type": "string", "enum": [ "variable", "constant" ], "description": "Origin of the options. `constant` means `value` lists the options literally; `variable` means `selector` points to an `array[string]` workflow variable that provides them." }, "selector": { "type": "array", "items": { "type": "string" }, "description": "Variable reference path when `type` is `variable`." }, "value": { "type": "array", "items": { "type": "string" }, "description": "Literal option list when `type` is `constant`." } } }, "allowed_file_types": { "type": "array", "items": { "type": "string", "enum": [ "image", "document", "audio", "video", "custom" ] }, "description": "File categories the recipient may upload. Present for `file` and `file-list` inputs. Values: `image`, `document`, `audio`, `video`, `custom`." }, "allowed_file_extensions": { "type": "array", "items": { "type": "string" }, "description": "Allowed file extensions when `allowed_file_types` includes `custom`. Include the leading `.` in each extension, for example `.md`. Present for `file` and `file-list` inputs." }, "allowed_file_upload_methods": { "type": "array", "items": { "type": "string", "enum": [ "local_file", "remote_url" ] }, "description": "Upload methods the recipient may use. Values: `local_file`, `remote_url`. Present for `file` and `file-list` inputs." }, "number_limits": { "type": "integer", "description": "Maximum number of files the recipient may upload. Present only for `file-list` inputs." } } }, "description": "Form input field definitions." }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Pre-rendered values to display in the form. Keyed by input `output_variable_name`. Populated for `paragraph` inputs whose default resolves from a workflow variable; empty for inputs with no resolvable default. Display these values; do not re-resolve `default` on the client. All values are stringified." }, "user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Identifier of the action button. Pass as `action` on [Submit Human Input Form](/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\nSubmit the recipient's response to a paused Human Input form. The workflow resumes on acceptance; follow subsequent events via the Stream Workflow Events endpoint. Requires WebApp delivery.", "operationId": "submitChatflowHumanInputForm", "parameters": [ { "name": "form_token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Access token for the paused form, returned in the `human_input_required` event from the Run Workflow or Send Chat Message endpoint in streaming mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs", "action", "user" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "Submitted values keyed by each input's `output_variable_name`. Paragraph and select inputs take a string; a `file` input takes one file mapping; a `file-list` input takes an array of file mappings. A file mapping is `{transfer_method: local_file, upload_file_id, type}` or `{transfer_method: remote_url, url, type}`, where `type` is one of the field's `allowed_file_types` (`image`, `document`, `audio`, `video`, `custom`). For `local_file`, `upload_file_id` is the `id` from [Upload File](/en/api-reference/files/upload-file). Use a consistent `user` across the run, upload, and submit." }, "action": { "type": "string", "description": "ID of the action button the recipient selected. Must match one of the `id` values from the form's `user_actions` list (returned by [Get Human Input Form](/en/api-reference/human-input/get-human-input-form))." }, "user": { "type": "string", "description": "Identifier for the end user, defined by your application's rules and unique within the app. Service API and WebApp user IDs are separate, even when identical." } } }, "examples": { "approve": { "summary": "Request Example", "value": { "inputs": { "feedback": "Looks good to ship", "priority": "high", "attachment": { "transfer_method": "local_file", "upload_file_id": "3c8fa1b2-7d4e-4f9a-b0c1-d2e3f4a5b6c7", "type": "image" }, "attachments": [ { "transfer_method": "local_file", "upload_file_id": "1a77f0df-c0e6-461c-987c-e72526f341ee", "type": "document" }, { "transfer_method": "remote_url", "url": "https://example.com/report.pdf", "type": "document" } ] }, "action": "approve", "user": "abc-123" } } } } } }, "responses": { "200": { "description": "Form submitted successfully. The response body is an empty object.", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "success": { "summary": "Response Example", "value": {} } } } } }, "400": { "description": "- `bad_request` : Form recipient type is invalid.\n- `invalid_form_data` : Submission failed validation against the form definition.", "content": { "application/json": { "examples": { "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Form recipient type is invalid" } }, "invalid_form_data": { "summary": "invalid_form_data", "value": { "status": 400, "code": "invalid_form_data", "message": "Missing required inputs: feedback" } } } } } }, "404": { "description": "`not_found` : Form not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Form not found" } } } } } }, "412": { "description": "- `human_input_form_submitted` : Form already submitted. Forms are one-shot; the first response wins regardless of which user submits it.\n- `human_input_form_expired` : The form's expiration time passed before submission arrived.", "content": { "application/json": { "examples": { "human_input_form_submitted": { "summary": "human_input_form_submitted", "value": { "status": 412, "code": "human_input_form_submitted", "message": "This form has already been submitted by another user, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "human_input_form_expired": { "summary": "human_input_form_expired", "value": { "status": 412, "code": "human_input_form_expired", "message": "This form has expired, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } }, "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": "The workflow run ID (the `workflow_run_id` from the original run response) whose event stream to resume." }, { "name": "user", "in": "query", "required": true, "schema": { "type": "string" }, "description": "End-user identifier that originally triggered the run. Must match the creator of the workflow run." }, { "name": "include_state_snapshot", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When `true`, replay from the persisted state snapshot to include a status summary of already-executed nodes before streaming new events." }, { "name": "continue_on_pause", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Set to `true` to keep the stream open across multiple `workflow_paused` events (useful when the workflow has more than one Human Input node in sequence). Default closes the stream after the first pause." } ], "responses": { "200": { "description": "Server-Sent Events stream. Each event is delivered as `data: {JSON}\\n\\n`. Event payloads follow the same schemas as the original streaming response.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE stream of events from a resumed workflow run, in the same format as [Run Workflow](/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\"}} 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\"}} 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\nExecute a workflow. Cannot be executed without 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 (SSE).\n\n**Parsing**: Each line begins with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing the JSON, then read the `event` field to determine the event type. Ignore `ping` events, which fire every 10 seconds to keep the connection alive.\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries no `message_id` or `conversation_id`. The parallel `text_chunk` stream stays free of `` 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` : Invalid parameter value.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "429": { "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal Server Error." } } } } } } }, "x-mint": { "href": "/en/api-reference/workflow-runs/run-workflow", "metadata": { "title": "Run Workflow", "sidebarTitle": "Run Workflow" } } } }, "/workflows/{workflow_id}/run": { "post": { "summary": "Run Workflow by ID", "description": "**Available for**: Workflow apps.\n\nExecute a specific workflow version identified by its ID. Useful for running a particular published version of the workflow.", "operationId": "runWorkflowById", "tags": [ "Workflow Runs" ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "description": "Workflow ID of the specific version to execute. This value is returned in the `workflow_id` field of [Run Workflow](/en/api-reference/workflow-runs/run-workflow) responses and [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { "example": { "summary": "Request Example", "value": { "inputs": { "query": "Summarize this article" }, "response_mode": "blocking", "user": "user_workflow_123" } } } } } }, "responses": { "200": { "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" }, "examples": { "blockingResponse": { "summary": "Response Example - Blocking mode", "value": { "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": { "result": "Article summary here" }, "error": null, "elapsed_time": 2.45, "total_tokens": 280, "total_steps": 4, "created_at": 1705407629, "finished_at": 1705407631 } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "A stream of Server-Sent Events (SSE).\n\n**Parsing**: Each line begins with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing the JSON, then read the `event` field to determine the event type. Ignore `ping` events, which fire every 10 seconds to keep the connection alive.\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries no `message_id` or `conversation_id`. The parallel `text_chunk` stream stays free of `` 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` : Required parameter missing or invalid.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Workflow is a draft and cannot be executed." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "404": { "description": "`not_found` : Workflow not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow not found." } } } } } }, "429": { "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal Server Error." } } } } } } }, "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, can be obtained from the streaming chunk return of the [Run Workflow](/en/api-reference/workflow-runs/run-workflow) API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "User identifier, used to attribute the stop request to an end user. It does not need to match the `user` passed to [Run Workflow](/en/api-reference/workflow-runs/run-workflow); the stop applies to the task regardless of user." } } }, "examples": { "example": { "summary": "Request Example", "value": { "user": "user_workflow_123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `invalid_param` : Required parameter missing or invalid.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } } }, "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\nSend a request to the text generation application.", "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 (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkCompletionEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `message_end` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." }, "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` : Required parameter missing or invalid.", "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" } } } }, "/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, can be obtained from the streaming chunk return of the [Send Completion Message](/en/api-reference/completion-messages/send-completion-message) API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "User identifier. Must match the `user` passed when the message was sent: if it differs, the stop silently does nothing and the response still returns success." } } }, "examples": { "example": { "summary": "Request Example", "value": { "user": "abc-123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `invalid_param` : Required parameter missing or invalid.", "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": "Create a new empty knowledge base. After creation, use [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) to add documents.", "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. Use the `provider` field from [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": "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` : Sorry, you have reached the knowledge base request rate limit of your subscription.", "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` : The dataset name already exists. Please modify your dataset name.", "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. Supports filtering by keyword and tags.", "operationId": "listDatasets", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number to retrieve." }, { "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." } ], "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": "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": "Retrieve detailed information about a specific 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." } ], "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": "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` : 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/knowledge-bases/get-knowledge-base", "metadata": { "title": "Get Knowledge Base", "sidebarTitle": "Get Knowledge Base" } } }, "patch": { "tags": [ "Knowledge Bases" ], "summary": "Update Knowledge Base", "description": "Update the name, description, permissions, or retrieval settings of an existing knowledge base. Only the fields provided in the request body are updated.", "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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. Use the `provider` field from [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": "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": [] } } } } } }, "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/knowledge-bases/update-knowledge-base", "metadata": { "title": "Update Knowledge Base", "sidebarTitle": "Update Knowledge Base" } } }, "delete": { "tags": [ "Knowledge Bases" ], "summary": "Delete Knowledge Base", "description": "Permanently delete a knowledge base and all its documents.", "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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/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": "Create a document from raw text content. The document is processed asynchronously — use the returned `batch` ID with [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status) to track progress.", "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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": "Processing mode. `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": "Retrieval model configuration. 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." } } } } } }, "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 valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\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` : Dataset 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` : 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/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": "Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status) to track progress.", "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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` : Please upload your file.\n- `too_many_files` : Only one file is allowed.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : External datasets are not supported, `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` : Dataset 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` : 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/documents/create-document-by-file", "metadata": { "title": "Create Document by File", "sidebarTitle": "Create Document by File" } } } }, "/datasets/{dataset_id}/documents": { "get": { "tags": [ "Documents" ], "summary": "List Documents", "description": "Returns a paginated list of documents in the knowledge base. Supports filtering by keyword and indexing status.", "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number to retrieve." }, { "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` : 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` : 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": "Retrieve detailed information about a specific document, including its indexing status, metadata, and processing statistics.", "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." }, { "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 response shape varies based on the `metadata` query parameter. When `metadata` is `only`, only `id`, `doc_type`, and `doc_metadata` are returned. When `metadata` is `without`, `doc_type` and `doc_metadata` are omitted.", "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` : No permission.\n- `forbidden` : Dataset 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 delete 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." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." } ], "responses": { "204": { "description": "Success." }, "403": { "description": "- `archived_document_immutable` : The archived document is not editable.\n- `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": { "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` : Document Not Exists.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document Not Exists." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/delete-document", "metadata": { "title": "Delete Document", "sidebarTitle": "Delete Document" } } }, "patch": { "tags": [ "Documents" ], "summary": "Update Document", "description": "Update an existing document by uploading a new file. This is the canonical endpoint for file-based document updates. Re-triggers indexing; use the returned `batch` ID with [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status) to track progress.", "operationId": "updateDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." } ], "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) (`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 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 valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\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_not_available": { "summary": "invalid_param (not available)", "value": { "status": 400, "code": "invalid_param", "message": "Document is not available" } } } } } }, "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.", "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` : File size exceeded.", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "File size exceeded." } } } } } }, "415": { "description": "`unsupported_file_type` : File type not allowed.", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "x-mint": { "href": "/en/api-reference/documents/update-document", "metadata": { "title": "Update Document", "sidebarTitle": "Update Document" } } } }, "/datasets/{dataset_id}/documents/{document_id}/download": { "get": { "tags": [ "Documents" ], "summary": "Download Document", "description": "Get a signed download URL for 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." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." } ], "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` : No permission.\n- `forbidden` : Dataset 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/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": "Check the indexing progress of documents in a batch. Returns the current processing stage and chunk completion counts for each document. Poll this endpoint until `indexing_status` reaches `completed` or `error`. The status progresses 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." }, { "name": "batch", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Batch ID returned from document creation." } ], "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", "description": "Unix timestamp when processing started." }, "parsing_completed_at": { "type": "number", "description": "Unix timestamp when parsing completed." }, "cleaning_completed_at": { "type": "number", "description": "Unix timestamp when cleaning completed." }, "splitting_completed_at": { "type": "number", "description": "Unix timestamp when splitting completed." }, "completed_at": { "type": "number", "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` : 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` : Knowledge base 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 an existing document's text content, name, or processing configuration. Re-triggers indexing when the content changes.", "operationId": "updateDocumentByText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." } ], "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": "Processing mode. `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": "Retrieval model configuration. 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 valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\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` : 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.", "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 an existing document by uploading a new file and re-triggers indexing.", "operationId": "updateDocumentByFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." } ], "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) (`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 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.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\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` : 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.", "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` : File size exceeded.", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "File size exceeded." } } } } } }, "415": { "description": "`unsupported_file_type` : File type not allowed.", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "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": "Download multiple uploaded-file documents as a single ZIP archive. Accepts up to `100` document IDs.", "operationId": "downloadDocumentsZip", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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": "Array of document IDs to include in the ZIP archive." } } } } } }, "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` : 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` : Document not found.\n- `not_found` : Dataset not found.", "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." } } } } } } }, "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": "Enable, disable, archive, or unarchive multiple documents at once.", "operationId": "batchUpdateDocumentStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "enable", "disable", "archive", "un_archive" ] }, "description": "`enable` to activate, `disable` to deactivate, `archive` to archive, `un_archive` to restore from archive." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_ids" ], "properties": { "document_ids": { "type": "array", "items": { "type": "string" }, "description": "List of document IDs to update." } } } } } }, "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` : 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` : 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. Each chunk requires `content`; `answer` is required for Q&A-mode (`qa_model`) documents. `keywords` are optional.", "operationId": "createSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." } ], "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 content for QA mode." }, "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` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Chunk validation failed (e.g. empty content) or the maximum number of chunks was exceeded.", "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_limit": { "summary": "invalid_param (segments limit)", "value": { "status": 400, "code": "invalid_param", "message": "Exceeded maximum segments limit of 1000." } } } } } }, "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. Supports filtering by keyword and status.", "operationId": "listSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number to retrieve." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 }, "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 } } } } } }, "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 detailed information about a specific chunk, including its content, keywords, and indexing status.", "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Chunk ID." } ], "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" } } } } } }, "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 content, keywords, or answer. Re-triggers indexing for the modified chunk.", "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Chunk ID." } ], "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 content for QA mode." }, "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` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\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 valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "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." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Chunk ID." } ], "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.\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." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "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 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": "`invalid_param` : Failed to create the child chunk index.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Create child chunk index failed." } } } } } }, "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." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Chunk ID." }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number to retrieve." }, { "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." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Chunk ID." }, { "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` : Failed to update the child chunk index.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Update child chunk index failed." } } } } } }, "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." }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Chunk ID." }, { "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` : Failed to delete the child chunk index.", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Delete child chunk index failed." } } } } } }, "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": "Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used 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." } ], "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." } } } } } }, "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 dataset is still being initialized or indexing. Please wait a moment.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.", "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 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": "Invalid parameter value." } } } } } }, "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` : Knowledge base not found.", "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 new 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." } } } } } }, "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" } } } } } } }, "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 the list of 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 an existing knowledge base tag.", "operationId": "updateKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tag_id", "name" ], "properties": { "tag_id": { "type": "string", "description": "Tag ID to update." }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "New tag name." } } } } } }, "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" } } } } } } }, "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": "Tag ID to delete." } } } } } }, "responses": { "204": { "description": "Success." } }, "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": "Tag IDs to bind." }, "target_id": { "type": "string", "description": "Knowledge base ID." } } } } } }, "responses": { "204": { "description": "Success." } }, "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." }, "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 ID." } } } } } }, "responses": { "204": { "description": "Success." } }, "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 list of tags bound to a specific knowledge base.", "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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 the knowledge base. Metadata fields can be used to annotate documents with structured information.", "operationId": "createMetadataField", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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": "Metadata field name." } } } } } }, "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 the list of all metadata fields (both custom and built-in) for the knowledge base, along 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." } ], "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." }, { "name": "metadata_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Metadata field ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "New metadata field name." } } } } } }, "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 using this field will lose their metadata values for it.", "operationId": "deleteMetadataField", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "metadata_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Metadata field ID." } ], "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 list of built-in metadata fields provided by the system (e.g., document type, source URL).", "operationId": "getBuiltInMetadataFields", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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." }, { "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 at once. Each document in the request receives the specified metadata key-value pairs.", "operationId": "batchUpdateDocumentMetadata", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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 whose metadata to update." }, "metadata_list": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Metadata field ID." }, "name": { "type": "string", "description": "Metadata field name." }, "value": { "description": "Metadata value. Can be a string, number, or `null`." } } } }, "partial_update": { "type": "boolean", "default": false, "description": "Whether to partially update metadata, keeping existing values for unspecified fields." } } }, "description": "Array of document metadata update operations. Each entry maps a document ID to its metadata key-value pairs." } } } } } }, "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 this knowledge base.", "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": "Retrieve the list of available models by type. Primarily used to query `text-embedding` and `rerank` models for knowledge base configuration.", "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, e.g. `openai`, `cohere`." }, "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." } } }, "icon_large": { "type": "object", "description": "URL of the provider's large icon.", "properties": { "en_US": { "type": "string", "description": "Large 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." } } } } } } } } }, "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "provider": "openai", "label": { "en_US": "OpenAI", "zh_Hans": "OpenAI" }, "icon_small": { "en_US": "https://example.com/openai-small.svg" }, "icon_large": { "en_US": "https://example.com/openai-large.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" } ] } ] } } } } } } }, "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": "Upload a file for use in a knowledge pipeline. Accepts a single file via `multipart/form-data`.", "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." } } } } } }, "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` : Please upload your file.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `too_many_files` : Only one file is allowed.", "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` : File size exceeded.", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "File size exceeded." } } } } } }, "415": { "description": "`unsupported_file_type` : File type not allowed.", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "x-mint": { "href": "/en/api-reference/knowledge-pipeline/upload-pipeline-file", "metadata": { "title": "Upload Pipeline File", "sidebarTitle": "Upload Pipeline File" } } } }, "/datasets/{dataset_id}/pipeline/datasource-plugins": { "get": { "tags": [ "Knowledge Pipeline" ], "summary": "List Datasource Plugins", "description": "List the datasource nodes configured in the knowledge pipeline. Each node includes the plugin it uses plus 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." }, { "name": "is_published", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "Whether to retrieve nodes from the published pipeline. Defaults to `true`, which returns nodes from the published version." } ], "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` : 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/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": "Execute a single datasource node within the knowledge pipeline. Returns a streaming response with the node execution results.", "operationId": "runDatasourceNode", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." }, { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the datasource node to execute." } ], "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 use for authentication with the datasource." }, "is_published": { "type": "boolean", "description": "Whether to run the published or draft version of the node. `true` runs the published version, `false` runs the draft." } } } } } }, "responses": { "200": { "description": "Streaming response with node execution events.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream containing node execution progress and results." } } } }, "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` : 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/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": "Execute the full knowledge pipeline for a knowledge base. Supports both streaming and blocking response modes.", "operationId": "runPipeline", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge base ID." } ], "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 pipeline execution from." }, "is_published": { "type": "boolean", "description": "Whether to run the published or draft version of the pipeline. `true` runs the latest published version; `false` runs the current draft (useful for testing 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`.\n\nEach line is `data: {JSON}\\n\\n`. Key events: `workflow_started` (execution began), `node_started` / `node_finished` (per-node progress with `node_id`, `node_type`, `status`, `inputs`, `outputs`), `workflow_finished` (final result with `status`, `outputs`, `total_tokens`, `elapsed_time`), `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` : 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." } } } } } }, "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": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.** Requests with a missing or invalid API key fail with HTTP `401` and error code `unauthorized`." } }, "responses": { "SuccessResult": { "description": "Operation successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "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": "User input/question content." }, "inputs": { "type": "object", "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs. Refer to the `user_input_form` field in the [Get App Parameters](/en/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", "additionalProperties": true }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes; not supported in Agent Assistant mode). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior. New Agent apps support `streaming` only; `blocking` returns 400 `bad_request`." }, "user": { "type": "string", "description": "User identifier, unique within the application. This identifier scopes data access — conversations, messages, and files are only visible when queried with the same `user` value." }, "conversation_id": { "type": "string", "description": "Conversation ID to continue a conversation. Pass the previous message's `conversation_id`. To start a new conversation, omit this field or pass an empty string. The response will return a `conversation_id` — pass it in subsequent messages to continue that conversation." }, "files": { "type": "array", "description": "File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/en/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`. Not supported for New Agent apps: file references are accepted but their contents are not processed.", "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." } } }, "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." }, "name": { "type": "string", "description": "File name." }, "size": { "type": "integer", "description": "File size in bytes." }, "extension": { "type": "string", "nullable": true, "description": "File extension." }, "mime_type": { "type": "string", "nullable": true, "description": "MIME type of the file." }, "created_by": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the user who uploaded the file." }, "created_at": { "type": "integer", "format": "int64", "description": "Upload timestamp (Unix epoch seconds)." }, "preview_url": { "type": "string", "nullable": true, "description": "Preview URL for the file." }, "source_url": { "type": "string", "description": "Signed URL for downloading the file." }, "original_url": { "type": "string", "nullable": true, "description": "Original URL of the file." }, "user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Unused; always `null`." }, "tenant_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the associated tenant." }, "conversation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the associated conversation." }, "file_key": { "type": "string", "nullable": true, "description": "Unused; always `null`." } } }, "EndUserDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "End user ID." }, "tenant_id": { "type": "string", "format": "uuid", "description": "Tenant ID." }, "app_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Application ID." }, "type": { "type": "string", "description": "End user type. Always `service_api` for Service API users." }, "external_user_id": { "type": "string", "nullable": true, "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/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": "User identifier, defined by the developer, must ensure uniqueness within the application." }, "content": { "type": "string", "description": "Optional text feedback providing additional detail." } } }, "AppFeedbacksResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "List of feedback items.", "items": { "$ref": "#/components/schemas/FeedbackItem" } } } }, "FeedbackItem": { "type": "object", "description": "A single feedback item.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Feedback ID." }, "app_id": { "type": "string", "format": "uuid", "description": "Application ID." }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "message_id": { "type": "string", "format": "uuid", "description": "Message ID." }, "rating": { "type": "string", "description": "Feedback rating. `like` for positive, `dislike` for negative." }, "content": { "type": "string", "nullable": true, "description": "Optional text feedback." }, "from_source": { "type": "string", "description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console." }, "from_end_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "End user ID who submitted the feedback. Present when `from_source` is `user`." }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Account ID who submitted the feedback. Present when `from_source` is `admin`." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp." } } }, "SuggestedQuestionsResponse": { "type": "object", "properties": { "result": { "type": "string", "description": "Result status." }, "data": { "type": "array", "items": { "type": "string" }, "description": "List of suggested questions." } } }, "ConversationHistoryResponse": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Number of items per page." }, "has_more": { "type": "boolean", "description": "Whether there are more messages." }, "data": { "type": "array", "description": "List of messages.", "items": { "$ref": "#/components/schemas/ConversationMessageItem" } } } }, "ConversationMessageItem": { "type": "object", "description": "A single message in a conversation.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Message ID." }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "parent_message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Parent message ID for threaded conversations." }, "inputs": { "type": "object", "additionalProperties": true, "description": "Input variables for this message." }, "query": { "type": "string", "description": "User query text." }, "answer": { "type": "string", "description": "Assistant answer text." }, "status": { "type": "string", "description": "Message status. `normal` for successful messages, `error` when generation failed." }, "error": { "type": "string", "nullable": true, "description": "Error message if `status` is `error`." }, "message_files": { "type": "array", "description": "Files attached to this message.", "items": { "$ref": "#/components/schemas/MessageFileItem" } }, "feedback": { "type": "object", "nullable": true, "description": "User feedback for this message.", "properties": { "rating": { "type": "string", "description": "Feedback rating. `like` for positive, `dislike` for negative." } } }, "retriever_resources": { "type": "array", "description": "Retriever resources used for this message.", "items": { "$ref": "#/components/schemas/RetrieverResource" } }, "agent_thoughts": { "type": "array", "description": "Agent thoughts for this message.", "items": { "$ref": "#/components/schemas/AgentThoughtItem" } }, "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp (Unix epoch seconds)." }, "extra_contents": { "type": "array", "description": "Additional execution content associated with this message, such as human input form data from Human Input nodes in Chatflow workflows.", "items": { "$ref": "#/components/schemas/HumanInputContent" } } } }, "MessageFileItem": { "type": "object", "description": "A file attached to a message.", "properties": { "id": { "type": "string", "format": "uuid", "description": "File ID." }, "filename": { "type": "string", "description": "Original filename." }, "type": { "type": "string", "description": "File type, e.g., `image`." }, "url": { "type": "string", "format": "url", "nullable": true, "description": "Preview URL for the file." }, "mime_type": { "type": "string", "nullable": true, "description": "MIME type of the file." }, "size": { "type": "integer", "nullable": true, "description": "File size in bytes." }, "transfer_method": { "type": "string", "description": "Transfer method used. `remote_url` for URL-based files, `local_file` for uploaded files, `tool_file` for tool-generated files." }, "belongs_to": { "type": "string", "nullable": true, "description": "Who this file belongs to. `user` for user-uploaded files, `assistant` for assistant-generated files." }, "upload_file_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Upload file ID if transferred via `local_file`." } } }, "AgentThoughtItem": { "type": "object", "description": "An agent thought step in the message.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent thought ID." }, "chain_id": { "type": "string", "nullable": true, "description": "Chain ID for this thought." }, "message_id": { "type": "string", "format": "uuid", "description": "Unique message ID this thought belongs to." }, "position": { "type": "integer", "description": "Position of this thought." }, "thought": { "type": "string", "description": "What LLM is thinking." }, "tool": { "type": "string", "description": "Tools called, split by `;`." }, "tool_labels": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Labels for tools used." }, "tool_input": { "type": "string", "description": "Input of tools in JSON format." }, "observation": { "type": "string", "description": "Response from tool calls." }, "files": { "type": "array", "items": { "type": "string" }, "description": "File IDs related to this thought." }, "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." } } }, "ConversationsListResponse": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Number of items per page." }, "has_more": { "type": "boolean", "description": "Whether there are more conversations." }, "data": { "type": "array", "description": "List of conversations.", "items": { "$ref": "#/components/schemas/ConversationListItem" } } } }, "ConversationListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "name": { "type": "string", "description": "Conversation name." }, "inputs": { "type": "object", "additionalProperties": true, "description": "Input variables for the conversation." }, "status": { "type": "string", "description": "Conversation status. `normal` for active conversations." }, "introduction": { "type": "string", "description": "Conversation introduction." }, "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." }, "updated_at": { "type": "integer", "format": "int64", "description": "Last update timestamp." } } }, "ConversationRenameRequest": { "type": "object", "description": "Request body for renaming a conversation.", "properties": { "name": { "type": "string", "description": "The name of the conversation. Required when `auto_generate` is `false`." }, "auto_generate": { "type": "boolean", "default": false, "description": "Automatically generate the conversation name. When `true`, the `name` field is ignored." }, "user": { "type": "string", "description": "The user identifier." } } }, "ConversationVariablesResponse": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Number of items per page." }, "has_more": { "type": "boolean", "description": "Whether there is a next page." }, "data": { "type": "array", "description": "List of conversation variables.", "items": { "$ref": "#/components/schemas/ConversationVariableItem" } } } }, "ConversationVariableItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Variable ID." }, "name": { "type": "string", "description": "Variable name." }, "value_type": { "type": "string", "description": "Variable value type. Possible values: `string`, `number`, `object`, `secret`, `file`, `boolean`, `array[any]`, `array[string]`, `array[number]`, `array[object]`, `array[file]`, `array[boolean]`." }, "value": { "type": "string", "description": "Variable value (can be a JSON string for complex types)." }, "description": { "type": "string", "description": "Variable description." }, "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." }, "updated_at": { "type": "integer", "format": "int64", "description": "Last update timestamp." } } }, "ConversationVariableUpdateRequest": { "type": "object", "description": "Request body for updating a conversation variable.", "required": [ "value" ], "properties": { "value": { "description": "The new value for the variable. Must match the variable's expected type." }, "user": { "type": "string", "description": "User identifier." } } }, "AudioToTextRequest": { "type": "object", "description": "Request body for audio-to-text conversion.", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file. Validated by MIME type: `audio/mp3`, `audio/m4a`, `audio/wav`, `audio/amr`, or `audio/mpga`. Limit: `30 MB`." }, "user": { "type": "string", "description": "User identifier." } } }, "AudioToTextResponse": { "type": "object", "properties": { "text": { "type": "string", "description": "Output text from speech recognition." } } }, "TextToAudioRequest": { "type": "object", "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", "properties": { "message_id": { "type": "string", "format": "uuid", "description": "Message ID. Takes priority over `text` when both are provided." }, "text": { "type": "string", "description": "Speech content to convert." }, "user": { "type": "string", "description": "User identifier." }, "voice": { "type": "string", "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/en/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." }, "streaming": { "type": "boolean", "description": "Whether to enable streaming response." } } }, "AppInfoResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Application name." }, "description": { "type": "string", "description": "Application description." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Application tags." }, "mode": { "type": "string", "description": "Application mode. `completion` for text generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for Chatflow apps, `workflow` for Workflow apps." }, "author_name": { "type": "string", "description": "Name of the application author." } } }, "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." }, "custom_disclaimer": { "type": "string", "description": "Custom disclaimer text." }, "default_language": { "type": "string", "description": "Default language code." }, "show_workflow_steps": { "type": "boolean", "description": "Whether to show workflow steps." }, "use_icon_as_answer_icon": { "type": "boolean", "description": "Whether to use the app icon as the answer icon." } } }, "AnnotationListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItem" }, "description": "List of annotation items for the current page." }, "has_more": { "type": "boolean", "description": "`true` if more pages are available beyond the current result set." }, "limit": { "type": "integer", "description": "Number of items per page." }, "total": { "type": "integer", "description": "Total number of annotations matching the query." }, "page": { "type": "integer", "description": "Current page number." } } }, "AnnotationItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique annotation identifier." }, "question": { "type": "string", "nullable": true, "description": "Question text that triggers this annotation." }, "answer": { "type": "string", "nullable": true, "description": "Predefined answer returned when the annotation is matched." }, "hit_count": { "type": "integer", "nullable": true, "description": "Number of times this annotation has been matched and returned as a reply." }, "created_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Creation timestamp (Unix epoch seconds)." } } }, "CreateAnnotationRequest": { "type": "object", "description": "Request body for creating a new annotation.", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "description": "Annotation question." }, "answer": { "type": "string", "description": "Annotation answer." } } }, "UpdateAnnotationRequest": { "type": "object", "description": "Request body for updating an annotation.", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "description": "Updated annotation question." }, "answer": { "type": "string", "description": "Updated annotation answer." } } }, "InitialAnnotationReplySettingsRequest": { "type": "object", "description": "Request body for configuring annotation reply settings.", "required": [ "score_threshold", "embedding_provider_name", "embedding_model_name" ], "properties": { "embedding_provider_name": { "type": "string", "description": "Name of the embedding model provider (e.g., `openai`, `cohere`)." }, "embedding_model_name": { "type": "string", "description": "Name of the embedding model to use for annotation matching (e.g., `text-embedding-3-small`)." }, "score_threshold": { "type": "number", "format": "float", "description": "Minimum similarity score for an annotation to be considered a match. Higher values require closer matches." } } }, "InitialAnnotationReplySettingsResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Asynchronous job ID. Use with [Get Annotation Reply Job Status](/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." } } } } } ] }, "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. Values for file-type variables should be arrays of file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`. Refer to the `user_input_form` field in the [Get App Parameters](/en/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" } } ] } }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events. When omitted, defaults to blocking behavior." }, "user": { "type": "string", "description": "User identifier, defined by the developer's rules, must be unique within the application. This identifier scopes data access — workflow runs and files are only visible when queried with the same `user` value." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, "nullable": true, "description": "File list. Suitable when files need to be combined with text for input, available only when the model supports Vision capability. To attach a local file, first upload it via [Upload File](/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." } } } } } ] }, "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": "Allows the entry of various variable values defined by the App. Contains key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. Refer to the `user_input_form` field in the [Get App Parameters](/en/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", "additionalProperties": true }, "query": { "type": "string", "default": "", "description": "The input text to be processed. This is a legacy parameter; in newer apps, the query should be passed inside the `inputs` object." }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior." }, "user": { "type": "string", "description": "User identifier, unique within the application. This identifier scopes data access — messages and files are only visible when queried with the same `user` value." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, "description": "File list for multimodal understanding, including images, documents, audio, and video. 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`." } } }, "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. Use the `provider` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`." }, "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": "Provider name of the reranking model." }, "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": "Provider name of the reranking model." }, "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. String operators (`contains`, `not contains`, `start with`, `end with`, `is`, `is not`, `empty`, `not empty`, `in`, `not in`) act on string or array metadata. Numeric operators (`=`, `≠`, `>`, `<`, `≥`, `≤`) act on numeric metadata. Time operators (`before`, `after`) act on time metadata.", "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" } ] } } } } } } } } } } }