{ "components": { "responses": { "SuccessResult": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "result": "success" } } }, "schema": { "properties": { "result": { "description": "Operation result. Always `success`.", "type": "string" } }, "type": "object" } } }, "description": "Operation successful." } }, "schemas": { "AgentThoughtItem": { "description": "An agent thought step in the message.", "properties": { "chain_id": { "description": "Chain ID for this thought.", "nullable": true, "type": "string" }, "created_at": { "description": "Creation timestamp.", "format": "int64", "type": "integer" }, "files": { "description": "File IDs related to this thought.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "Agent thought ID.", "format": "uuid", "type": "string" }, "message_id": { "description": "Unique message ID this thought belongs to.", "format": "uuid", "type": "string" }, "observation": { "description": "Response from tool calls.", "type": "string" }, "position": { "description": "Position of this thought.", "type": "integer" }, "thought": { "description": "What LLM is thinking.", "type": "string" }, "tool": { "description": "Tools called, split by `;`.", "type": "string" }, "tool_input": { "description": "Input of tools in JSON format.", "type": "string" }, "tool_labels": { "additionalProperties": true, "description": "Labels for tools used.", "nullable": true, "type": "object" } }, "type": "object" }, "AnnotationItem": { "properties": { "answer": { "description": "Predefined answer returned when the annotation is matched.", "nullable": true, "type": "string" }, "created_at": { "description": "Creation timestamp (Unix epoch seconds).", "format": "int64", "nullable": true, "type": "integer" }, "hit_count": { "description": "Number of times this annotation has been matched and returned as a reply.", "nullable": true, "type": "integer" }, "id": { "description": "Unique annotation identifier.", "format": "uuid", "type": "string" }, "question": { "description": "Question text that triggers this annotation.", "nullable": true, "type": "string" } }, "type": "object" }, "AnnotationListResponse": { "properties": { "data": { "description": "List of annotation items for the current page.", "items": { "$ref": "#/components/schemas/AnnotationItem" }, "type": "array" }, "has_more": { "description": "`true` if more pages are available beyond the current result set.", "type": "boolean" }, "limit": { "description": "Number of items per page.", "type": "integer" }, "page": { "description": "Current page number.", "type": "integer" }, "total": { "description": "Total number of annotations matching the query.", "type": "integer" } }, "type": "object" }, "AppFeedbacksResponse": { "properties": { "data": { "description": "List of feedback items.", "items": { "$ref": "#/components/schemas/FeedbackItem" }, "type": "array" } }, "type": "object" }, "AppInfoResponse": { "properties": { "author_name": { "description": "Name of the application author.", "type": "string" }, "description": { "description": "Application description.", "type": "string" }, "mode": { "description": "Application mode. `completion` for Text Generator apps, `chat` for Chatbot apps, `agent-chat` for Legacy Agent apps, `advanced-chat` for Chatflow apps, `workflow` for Workflow apps, `agent` for Agent apps.", "type": "string" }, "name": { "description": "Application name.", "type": "string" }, "tags": { "description": "Application tags.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "AppMetaResponse": { "properties": { "tool_icons": { "additionalProperties": { "oneOf": [ { "description": "URL of the icon.", "format": "url", "title": "Icon URL", "type": "string" }, { "$ref": "#/components/schemas/ToolIconDetail" } ] }, "description": "Tool icons. Keys are tool names.", "type": "object" } }, "type": "object" }, "AppParametersResponse": { "properties": { "annotation_reply": { "description": "Annotation reply feature configuration.", "properties": { "enabled": { "description": "Whether this feature is enabled.", "type": "boolean" } }, "type": "object" }, "file_upload": { "description": "File upload configuration.", "properties": { "image": { "properties": { "detail": { "description": "Image detail level for vision models.", "type": "string" }, "enabled": { "description": "Whether image upload is enabled.", "type": "boolean" }, "number_limits": { "description": "Maximum number of images that can be uploaded.", "type": "integer" }, "transfer_methods": { "description": "Allowed transfer methods for image upload. `remote_url` for file URL, `local_file` for uploaded file.", "items": { "type": "string" }, "type": "array" } }, "type": "object" } }, "type": "object" }, "more_like_this": { "description": "More-like-this feature configuration.", "properties": { "enabled": { "description": "Whether this feature is enabled.", "type": "boolean" } }, "type": "object" }, "opening_statement": { "description": "Opening statement text.", "nullable": true, "type": "string" }, "retriever_resource": { "description": "Knowledge retrieval citation resource configuration.", "properties": { "enabled": { "description": "Whether this feature is enabled.", "type": "boolean" } }, "type": "object" }, "sensitive_word_avoidance": { "description": "Content moderation feature configuration.", "properties": { "enabled": { "description": "Whether this feature is enabled.", "type": "boolean" } }, "type": "object" }, "speech_to_text": { "description": "Speech-to-text feature configuration.", "properties": { "enabled": { "description": "Whether this feature is enabled.", "type": "boolean" } }, "type": "object" }, "suggested_questions": { "description": "List of suggested questions.", "items": { "type": "string" }, "type": "array" }, "suggested_questions_after_answer": { "description": "Configuration for suggested questions after an answer.", "properties": { "enabled": { "description": "Whether this feature is enabled.", "type": "boolean" } }, "type": "object" }, "system_parameters": { "description": "System-level parameter limits.", "properties": { "audio_file_size_limit": { "description": "Maximum audio file size in MB.", "type": "integer" }, "file_size_limit": { "description": "Maximum general file size in MB.", "type": "integer" }, "image_file_size_limit": { "description": "Maximum image file size in MB.", "type": "integer" }, "video_file_size_limit": { "description": "Maximum video file size in MB.", "type": "integer" }, "workflow_file_upload_limit": { "description": "Maximum number of files per workflow execution.", "type": "integer" } }, "type": "object" }, "text_to_speech": { "description": "Text-to-speech feature configuration.", "properties": { "autoPlay": { "description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play.", "type": "string" }, "enabled": { "description": "Whether this feature is enabled.", "type": "boolean" }, "language": { "description": "Language for TTS.", "type": "string" }, "voice": { "description": "Voice identifier for TTS.", "type": "string" } }, "type": "object" }, "user_input_form": { "description": "User input form configuration.", "items": { "oneOf": [ { "properties": { "text-input": { "properties": { "default": { "description": "Default value for the input field.", "type": "string" }, "label": { "description": "Display label for the input field.", "type": "string" }, "required": { "description": "Whether this field is required.", "type": "boolean" }, "variable": { "description": "Variable name used in the workflow.", "type": "string" } }, "type": "object" } }, "title": "Text Input", "type": "object" }, { "properties": { "paragraph": { "properties": { "default": { "description": "Default value for the paragraph field.", "type": "string" }, "label": { "description": "Display label for the paragraph field.", "type": "string" }, "required": { "description": "Whether this field is required.", "type": "boolean" }, "variable": { "description": "Variable name used in the workflow.", "type": "string" } }, "type": "object" } }, "title": "Paragraph", "type": "object" }, { "properties": { "select": { "properties": { "default": { "description": "Default selected value.", "type": "string" }, "label": { "description": "Display label for the select field.", "type": "string" }, "options": { "description": "List of selectable values for this form control.", "items": { "type": "string" }, "type": "array" }, "required": { "description": "Whether this field is required.", "type": "boolean" }, "variable": { "description": "Variable name used in the workflow.", "type": "string" } }, "type": "object" } }, "title": "Select", "type": "object" } ], "type": "object" }, "type": "array" } }, "type": "object" }, "AudioToTextRequest": { "description": "Request body for audio-to-text conversion.", "properties": { "file": { "description": "Audio file to transcribe. Accepted MIME types: `audio/mp3`, `audio/m4a` (also accepted as `audio/x-m4a`), `audio/wav`, `audio/amr`, `audio/mpga`. Other types, including the common `audio/mpeg`, are rejected with `unsupported_audio_type`. Maximum size `30 MB`.", "format": "binary", "type": "string" }, "user": { "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "required": [ "file" ], "type": "object" }, "AudioToTextResponse": { "properties": { "text": { "description": "Output text from speech recognition.", "type": "string" } }, "type": "object" }, "ChatCompletionResponse": { "properties": { "answer": { "description": "Complete response content.", "type": "string" }, "conversation_id": { "description": "Conversation ID.", "format": "uuid", "type": "string" }, "created_at": { "description": "Message creation timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "event": { "description": "Event type, fixed as `message`.", "type": "string" }, "id": { "description": "Unique ID of this response event.", "format": "uuid", "type": "string" }, "message_id": { "description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints.", "format": "uuid", "type": "string" }, "metadata": { "description": "Metadata including usage and retriever resources.", "properties": { "retriever_resources": { "description": "List of retriever resources used.", "items": { "$ref": "#/components/schemas/RetrieverResource" }, "type": "array" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "type": "object" }, "mode": { "description": "App mode. `chat` for Chatbot apps, `agent-chat` for Legacy Agent apps, `advanced-chat` for Chatflow apps.", "type": "string" }, "task_id": { "description": "Task ID for request tracking and stop response API.", "format": "uuid", "type": "string" } }, "type": "object" }, "ChatRequest": { "properties": { "auto_generate_name": { "default": true, "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.", "type": "boolean" }, "conversation_id": { "description": "ID of the conversation to continue. Omit it or pass an empty string to start a new conversation; the response returns a `conversation_id` to send with the next message. To resume an earlier conversation, get its ID from [List Conversations](/en/api-reference/conversations/list-conversations).", "type": "string" }, "files": { "description": "Files to attach to the message. For a local file, first upload it via [Upload File](/en/api-reference/files/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`. Agent apps accept file references but do not process their contents.", "items": { "properties": { "transfer_method": { "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file.", "enum": [ "remote_url", "local_file" ], "type": "string" }, "type": { "description": "File type.", "enum": [ "image", "document", "audio", "video", "custom" ], "type": "string" }, "upload_file_id": { "description": "Uploaded file ID obtained from the [Upload File](/en/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`).", "type": "string" }, "url": { "description": "File URL (required when `transfer_method` is `remote_url`).", "format": "url", "type": "string" } }, "required": [ "type", "transfer_method" ], "type": "object" }, "type": "array" }, "inputs": { "additionalProperties": true, "description": "Values for the app's input variables, keyed by variable name. The expected names and types come from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).", "type": "object" }, "query": { "description": "The user's message.", "type": "string" }, "response_mode": { "description": "Mode of response return. Defaults to blocking when omitted.\n\n- `streaming` (recommended): the reply arrives as Server-Sent Events.\n- `blocking`: returns once generation completes. Long generations risk interruption: on Dify Cloud, the edge proxy may end the connection if the response doesn't arrive within its timeout.\n- Legacy Agent and Agent apps support `streaming` only; a `blocking` request fails with 400.", "enum": [ "streaming", "blocking" ], "type": "string" }, "user": { "description": "End-user identifier, defined by your app and unique within it. Conversations, messages, and files are visible only to requests carrying the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" }, "workflow_id": { "description": "Chatflow apps only. Specify a published workflow version ID to execute. If not provided, the latest published version is used. On Dify Cloud, pinning a version requires a paid plan.", "type": "string" } }, "required": [ "inputs", "query", "user" ], "type": "object" }, "ChildChunk": { "properties": { "content": { "description": "Text content of the child chunk.", "type": "string" }, "created_at": { "description": "Creation timestamp (Unix epoch in seconds).", "type": "number" }, "id": { "description": "Unique identifier of the child chunk.", "type": "string" }, "position": { "description": "Position of the child chunk within the parent chunk.", "type": "integer" }, "segment_id": { "description": "ID of the parent chunk this child chunk belongs to.", "type": "string" }, "type": { "description": "How the child chunk was created. Child chunks created or updated through the API are always `customized`. System-generated child chunks are `automatic`.", "type": "string" }, "updated_at": { "description": "Last update timestamp (Unix epoch in seconds).", "type": "number" }, "word_count": { "description": "Word count of the child chunk content.", "type": "integer" } }, "type": "object" }, "ChunkChatEvent": { "description": "Base schema for Server-Sent Event chunks in streaming mode.", "discriminator": { "mapping": { "agent_log": "#/components/schemas/StreamEventAgentLog", "agent_message": "#/components/schemas/StreamEventChatAgentMessage", "agent_thought": "#/components/schemas/StreamEventChatAgentThought", "error": "#/components/schemas/StreamEventChatError", "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout", "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", "iteration_next": "#/components/schemas/StreamEventIterationNext", "iteration_started": "#/components/schemas/StreamEventIterationStarted", "loop_completed": "#/components/schemas/StreamEventLoopCompleted", "loop_next": "#/components/schemas/StreamEventLoopNext", "loop_started": "#/components/schemas/StreamEventLoopStarted", "message": "#/components/schemas/StreamEventChatMessage", "message_end": "#/components/schemas/StreamEventChatMessageEnd", "message_file": "#/components/schemas/StreamEventChatMessageFile", "message_replace": "#/components/schemas/StreamEventChatMessageReplace", "node_finished": "#/components/schemas/StreamEventNodeFinished", "node_retry": "#/components/schemas/StreamEventNodeRetry", "node_started": "#/components/schemas/StreamEventNodeStarted", "ping": "#/components/schemas/StreamEventChatPing", "reasoning_chunk": "#/components/schemas/StreamEventChatReasoningChunk", "text_chunk": "#/components/schemas/StreamEventChatTextChunk", "tts_message": "#/components/schemas/StreamEventChatTtsMessage", "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", "workflow_started": "#/components/schemas/StreamEventWorkflowStarted" }, "propertyName": "event" }, "properties": { "event": { "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" ], "type": "string" } }, "type": "object" }, "ChunkCompletionEvent": { "discriminator": { "mapping": { "error": "#/components/schemas/CompletionStreamEventError", "message": "#/components/schemas/StreamEventMessage", "message_end": "#/components/schemas/StreamEventMessageEnd", "message_file": "#/components/schemas/StreamEventMessageFile", "message_replace": "#/components/schemas/StreamEventMessageReplace", "ping": "#/components/schemas/CompletionStreamEventPing", "tts_message": "#/components/schemas/CompletionStreamEventTtsMessage", "tts_message_end": "#/components/schemas/CompletionStreamEventTtsMessageEnd" }, "propertyName": "event" }, "properties": { "event": { "description": "The type of streaming event.", "enum": [ "message", "message_end", "message_file", "tts_message", "tts_message_end", "message_replace", "error", "ping" ], "type": "string" } }, "type": "object" }, "ChunkWorkflowEvent": { "discriminator": { "mapping": { "agent_log": "#/components/schemas/WorkflowStreamEventAgentLog", "error": "#/components/schemas/StreamEventError", "human_input_form_filled": "#/components/schemas/WorkflowStreamEventHumanInputFormFilled", "human_input_form_timeout": "#/components/schemas/WorkflowStreamEventHumanInputFormTimeout", "human_input_required": "#/components/schemas/WorkflowStreamEventHumanInputRequired", "iteration_completed": "#/components/schemas/WorkflowStreamEventIterationCompleted", "iteration_next": "#/components/schemas/WorkflowStreamEventIterationNext", "iteration_started": "#/components/schemas/WorkflowStreamEventIterationStarted", "loop_completed": "#/components/schemas/WorkflowStreamEventLoopCompleted", "loop_next": "#/components/schemas/WorkflowStreamEventLoopNext", "loop_started": "#/components/schemas/WorkflowStreamEventLoopStarted", "node_finished": "#/components/schemas/WorkflowStreamEventNodeFinished", "node_retry": "#/components/schemas/WorkflowStreamEventNodeRetry", "node_started": "#/components/schemas/WorkflowStreamEventNodeStarted", "ping": "#/components/schemas/StreamEventPing", "reasoning_chunk": "#/components/schemas/StreamEventReasoningChunk", "text_chunk": "#/components/schemas/StreamEventTextChunk", "tts_message": "#/components/schemas/StreamEventTtsMessage", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", "workflow_finished": "#/components/schemas/WorkflowStreamEventWorkflowFinished", "workflow_paused": "#/components/schemas/WorkflowStreamEventWorkflowPaused", "workflow_started": "#/components/schemas/WorkflowStreamEventWorkflowStarted" }, "propertyName": "event" }, "properties": { "event": { "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" ], "type": "string" } }, "required": [ "event" ], "type": "object" }, "CompletionRequest": { "properties": { "files": { "description": "Files to attach to the request. For a local file, first upload it via [Upload File](/en/api-reference/files/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`.", "items": { "$ref": "#/components/schemas/InputFileObject" }, "type": "array" }, "inputs": { "additionalProperties": true, "description": "Values for the app's input variables, keyed by variable name. The expected names and types come from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).", "type": "object" }, "query": { "default": "", "description": "The text to process. Legacy field; newer apps pass this inside `inputs` instead.", "type": "string" }, "response_mode": { "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.", "enum": [ "streaming", "blocking" ], "type": "string" }, "user": { "description": "End-user identifier, defined by your app and unique within it. Messages and files are visible only to requests carrying the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "required": [ "inputs", "user" ], "type": "object" }, "CompletionResponse": { "properties": { "answer": { "description": "Complete response content.", "type": "string" }, "created_at": { "description": "Message creation timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "event": { "description": "Event type, fixed as `message`.", "type": "string" }, "id": { "description": "Unique ID of this response event.", "format": "uuid", "type": "string" }, "message_id": { "description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints.", "format": "uuid", "type": "string" }, "metadata": { "description": "Metadata including usage and retriever resources.", "properties": { "retriever_resources": { "description": "List of retriever resources used.", "items": { "$ref": "#/components/schemas/RetrieverResource" }, "type": "array" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "type": "object" }, "mode": { "description": "App mode, fixed as `completion`.", "type": "string" }, "task_id": { "description": "Task ID for request tracking and the [Stop Completion Message Generation](/en/api-reference/completion-messages/stop-completion-message-generation) API.", "format": "uuid", "type": "string" } }, "type": "object" }, "CompletionStreamEventBase": { "properties": { "created_at": { "description": "Creation timestamp.", "format": "int64", "type": "integer" }, "message_id": { "description": "Unique message ID.", "format": "uuid", "type": "string" }, "task_id": { "description": "Task ID.", "format": "uuid", "type": "string" } }, "type": "object" }, "CompletionStreamEventError": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "description": "Error event during streaming.", "properties": { "code": { "description": "Error code.", "type": "string" }, "message": { "description": "Error message.", "type": "string" }, "status": { "description": "HTTP status code.", "type": "integer" } }, "type": "object" } ] }, "CompletionStreamEventPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "description": "Ping event to keep connection alive. Delivered as an `event: ping` line with no `data:` payload.", "type": "object" } ] }, "CompletionStreamEventTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "description": "TTS audio stream event (base64 encoded MP3). Available if auto-play is enabled.", "properties": { "audio": { "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file.", "format": "byte", "type": "string" } }, "type": "object" } ] }, "CompletionStreamEventTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "description": "TTS audio stream end event.", "properties": { "audio": { "description": "Empty string. Signals the end of the audio stream.", "type": "string" } }, "type": "object" } ] }, "ConversationHistoryResponse": { "properties": { "data": { "description": "List of messages.", "items": { "$ref": "#/components/schemas/ConversationMessageItem" }, "type": "array" }, "has_more": { "description": "Whether there are more messages.", "type": "boolean" }, "limit": { "description": "Number of items per page.", "type": "integer" } }, "type": "object" }, "ConversationListItem": { "properties": { "created_at": { "description": "Creation timestamp.", "format": "int64", "type": "integer" }, "id": { "description": "Conversation ID.", "format": "uuid", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Input variables for the conversation.", "type": "object" }, "introduction": { "description": "Conversation introduction.", "type": "string" }, "name": { "description": "Conversation name.", "type": "string" }, "status": { "description": "Conversation status. `normal` for active conversations.", "type": "string" }, "updated_at": { "description": "Last update timestamp.", "format": "int64", "type": "integer" } }, "type": "object" }, "ConversationMessageItem": { "properties": { "agent_thoughts": { "description": "Agent thoughts for this message.", "items": { "$ref": "#/components/schemas/AgentThoughtItem" }, "type": "array" }, "answer": { "description": "Assistant answer text.", "type": "string" }, "answer_tokens": { "description": "Number of tokens in the generated answer.", "type": "integer" }, "conversation_id": { "description": "Conversation ID.", "format": "uuid", "type": "string" }, "created_at": { "description": "Creation timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "currency": { "description": "Currency for `total_price` (for example, `USD`), or `null` when pricing is unavailable.", "nullable": true, "type": "string" }, "error": { "description": "Error message if `status` is `error`.", "nullable": true, "type": "string" }, "extra_contents": { "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" }, "type": "array" }, "feedback": { "description": "User feedback for this message.", "nullable": true, "properties": { "rating": { "description": "Feedback rating. `like` for positive, `dislike` for negative.", "type": "string" } }, "type": "object" }, "id": { "description": "Message ID.", "format": "uuid", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Input variables for this message.", "type": "object" }, "message_files": { "description": "Files attached to this message.", "items": { "$ref": "#/components/schemas/MessageFileItem" }, "type": "array" }, "message_tokens": { "description": "Number of tokens in the input message.", "type": "integer" }, "parent_message_id": { "description": "Parent message ID for threaded conversations.", "format": "uuid", "nullable": true, "type": "string" }, "provider_response_latency": { "description": "Model provider response latency in seconds.", "format": "double", "type": "number" }, "query": { "description": "User query text.", "type": "string" }, "retriever_resources": { "description": "Retriever resources used for this message.", "items": { "$ref": "#/components/schemas/RetrieverResource" }, "type": "array" }, "status": { "description": "Message status. `normal` for successful messages, `error` when generation failed.", "type": "string" }, "total_price": { "description": "Total price for the tokens used, or `null` when pricing is unavailable.", "format": "decimal", "nullable": true, "type": "string" }, "total_tokens": { "description": "Total tokens used, the sum of `message_tokens` and `answer_tokens`.", "type": "integer" } }, "type": "object" }, "ConversationRenameRequest": { "description": "Request body for renaming a conversation.", "properties": { "auto_generate": { "default": false, "description": "Automatically generate the conversation name. When `true`, the `name` field is ignored.", "type": "boolean" }, "name": { "description": "New conversation name. Required unless `auto_generate` is `true`.", "type": "string" }, "user": { "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "type": "object" }, "ConversationVariableItem": { "properties": { "created_at": { "description": "Creation timestamp.", "format": "int64", "type": "integer" }, "description": { "description": "Variable description.", "type": "string" }, "id": { "description": "Variable ID.", "format": "uuid", "type": "string" }, "name": { "description": "Variable name.", "type": "string" }, "updated_at": { "description": "Last update timestamp.", "format": "int64", "type": "integer" }, "value": { "description": "Variable value (can be a JSON string for complex types).", "type": "string" }, "value_type": { "description": "Variable value type. Possible values: `string`, `number`, `object`, `secret`, `file`, `boolean`, `array[any]`, `array[string]`, `array[number]`, `array[object]`, `array[file]`, `array[boolean]`.", "type": "string" } }, "type": "object" }, "ConversationVariableUpdateRequest": { "description": "Request body for updating a conversation variable.", "properties": { "user": { "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" }, "value": { "description": "The new value for the variable. Must match the variable's expected type." } }, "required": [ "value" ], "type": "object" }, "ConversationVariablesResponse": { "properties": { "data": { "description": "List of conversation variables.", "items": { "$ref": "#/components/schemas/ConversationVariableItem" }, "type": "array" }, "has_more": { "description": "Whether there is a next page.", "type": "boolean" }, "limit": { "description": "Number of items per page.", "type": "integer" } }, "type": "object" }, "ConversationsListResponse": { "properties": { "data": { "description": "List of conversations.", "items": { "$ref": "#/components/schemas/ConversationListItem" }, "type": "array" }, "has_more": { "description": "Whether there are more conversations.", "type": "boolean" }, "limit": { "description": "Number of items per page.", "type": "integer" } }, "type": "object" }, "CreateAnnotationRequest": { "description": "Request body for creating a new annotation.", "properties": { "answer": { "description": "Answer returned when this annotation is matched.", "type": "string" }, "question": { "description": "Question text the app matches incoming user input against.", "type": "string" } }, "required": [ "question", "answer" ], "type": "object" }, "Dataset": { "properties": { "app_count": { "description": "Number of applications currently using this knowledge base.", "type": "integer" }, "author_name": { "description": "Display name of the creator.", "type": "string" }, "built_in_field_enabled": { "description": "Whether built-in metadata fields (e.g., `document_name`, `uploader`) are enabled.", "type": "boolean" }, "chunk_structure": { "description": "Chunk structure configuration.", "nullable": true, "type": "string" }, "created_at": { "description": "Creation timestamp (Unix epoch in seconds).", "type": "number" }, "created_by": { "description": "ID of the user who created the knowledge base.", "type": "string" }, "data_source_type": { "description": "Data source type of the documents, `null` if not yet configured.", "type": "string" }, "description": { "description": "Optional text describing the purpose or contents of the knowledge base.", "type": "string" }, "doc_form": { "description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction.", "type": "string" }, "doc_metadata": { "description": "Metadata field definitions for the knowledge base.", "items": { "properties": { "id": { "description": "Metadata field identifier.", "type": "string" }, "name": { "description": "Metadata field name.", "type": "string" }, "type": { "description": "Metadata field value type.", "type": "string" } }, "type": "object" }, "type": "array" }, "document_count": { "description": "Total number of documents in the knowledge base.", "type": "integer" }, "embedding_available": { "description": "Whether the configured embedding model is currently available.", "type": "boolean" }, "embedding_model": { "description": "Name of the embedding model used for indexing.", "type": "string" }, "embedding_model_provider": { "description": "Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). Legacy knowledge bases may return the bare short form (e.g. `openai`).", "type": "string" }, "enable_api": { "description": "Whether API access is enabled for this knowledge base.", "type": "boolean" }, "external_knowledge_info": { "description": "Connection details for external knowledge bases. Present when `provider` is `external`.", "nullable": true, "properties": { "external_knowledge_api_endpoint": { "description": "Endpoint URL of the external knowledge API.", "type": "string" }, "external_knowledge_api_id": { "description": "ID of the external knowledge API connection.", "type": "string" }, "external_knowledge_api_name": { "description": "Display name of the external knowledge API.", "type": "string" }, "external_knowledge_id": { "description": "ID of the external knowledge base.", "type": "string" } }, "type": "object" }, "external_retrieval_model": { "description": "Retrieval settings for external knowledge bases. `null` for internal knowledge bases.", "nullable": true, "properties": { "score_threshold": { "description": "Minimum similarity score threshold.", "type": "number" }, "score_threshold_enabled": { "description": "Whether score threshold filtering is enabled.", "type": "boolean" }, "top_k": { "description": "Maximum number of results to return from the external knowledge base.", "type": "integer" } }, "type": "object" }, "icon_info": { "description": "Icon display configuration for the knowledge base.", "nullable": true, "properties": { "icon": { "description": "Icon identifier or emoji.", "type": "string" }, "icon_background": { "description": "Background color for the icon.", "type": "string" }, "icon_type": { "description": "Type of icon.", "type": "string" }, "icon_url": { "description": "URL of a custom icon image.", "type": "string" } }, "type": "object" }, "id": { "description": "Unique identifier of the knowledge base.", "type": "string" }, "indexing_technique": { "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.", "type": "string" }, "is_multimodal": { "description": "Whether multimodal content processing is enabled.", "type": "boolean" }, "is_published": { "description": "Whether the knowledge base is published.", "type": "boolean" }, "maintainer": { "description": "Display name of the knowledge base maintainer. `null` if not set.", "nullable": true, "type": "string" }, "name": { "description": "Display name of the knowledge base. Unique within the workspace.", "type": "string" }, "partial_member_list": { "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`.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "permission": { "description": "Controls who can access this knowledge base. Possible values: `only_me`, `all_team_members`, `partial_members`.", "type": "string" }, "pipeline_id": { "description": "Pipeline ID, if a custom processing pipeline is configured.", "nullable": true, "type": "string" }, "provider": { "description": "Provider type. `vendor` for internally managed, `external` for external knowledge base connections.", "type": "string" }, "retrieval_model_dict": { "description": "Retrieval configuration for the knowledge base.", "properties": { "reranking_enable": { "description": "Whether reranking is enabled.", "type": "boolean" }, "reranking_mode": { "description": "Reranking mode. `reranking_model` for model-based reranking, `weighted_score` for score-based weighting. `null` if reranking is disabled.", "nullable": true, "type": "string" }, "reranking_model": { "description": "Reranking model configuration.", "properties": { "reranking_model_name": { "description": "Name of the reranking model.", "type": "string" }, "reranking_provider_name": { "description": "Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). Legacy knowledge bases may return the bare short form (e.g. `cohere`).", "type": "string" } }, "type": "object" }, "score_threshold": { "description": "Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`.", "type": "number" }, "score_threshold_enabled": { "description": "Whether score threshold filtering is enabled.", "type": "boolean" }, "search_method": { "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.", "type": "string" }, "top_k": { "description": "Maximum number of results to return.", "type": "integer" }, "weights": { "description": "Weight configuration for hybrid search.", "nullable": true, "properties": { "keyword_setting": { "description": "Keyword search weight settings.", "properties": { "keyword_weight": { "description": "Weight assigned to keyword search results.", "type": "number" } }, "type": "object" }, "vector_setting": { "description": "Semantic search weight settings.", "properties": { "embedding_model_name": { "description": "Name of the embedding model used for vector search.", "type": "string" }, "embedding_provider_name": { "description": "Provider of the embedding model used for vector search.", "type": "string" }, "vector_weight": { "description": "Weight assigned to semantic (vector) search results.", "type": "number" } }, "type": "object" }, "weight_type": { "description": "Strategy for balancing semantic and keyword search weights.", "type": "string" } }, "type": "object" } }, "type": "object" }, "runtime_mode": { "description": "Runtime processing mode.", "nullable": true, "type": "string" }, "summary_index_setting": { "description": "Summary index configuration.", "nullable": true, "properties": { "enable": { "description": "Whether summary indexing is enabled.", "type": "boolean" }, "model_name": { "description": "Name of the model used for generating summaries.", "type": "string" }, "model_provider_name": { "description": "Provider of the summary generation model.", "type": "string" }, "summary_prompt": { "description": "Prompt template used for summary generation.", "type": "string" } }, "type": "object" }, "tags": { "description": "Tags associated with this knowledge base.", "items": { "properties": { "id": { "description": "Tag identifier.", "type": "string" }, "name": { "description": "Tag name.", "type": "string" }, "type": { "description": "Tag type. Always `knowledge` for knowledge base tags.", "type": "string" } }, "type": "object" }, "type": "array" }, "total_available_documents": { "description": "Number of documents that are enabled and available.", "type": "integer" }, "total_documents": { "description": "Total number of documents.", "type": "integer" }, "updated_at": { "description": "Last update timestamp (Unix epoch in seconds).", "type": "number" }, "updated_by": { "description": "ID of the user who last updated the knowledge base.", "type": "string" }, "word_count": { "description": "Total word count across all documents.", "type": "integer" } }, "type": "object" }, "Document": { "properties": { "archived": { "description": "Whether the document is archived.", "type": "boolean" }, "created_at": { "description": "Creation timestamp (Unix epoch in seconds).", "type": "number" }, "created_by": { "description": "ID of the user who created the document.", "type": "string" }, "created_from": { "description": "Origin of the document. `api` for API creation, `web` for UI creation.", "type": "string" }, "data_source_detail_dict": { "description": "Detailed data source information including file details.", "type": "object" }, "data_source_info": { "description": "Raw data source information, varies by `data_source_type`.", "type": "object" }, "data_source_type": { "description": "How the document was created. `upload_file` for file uploads, `notion_import` for Notion imports.", "type": "string" }, "dataset_process_rule_id": { "description": "ID of the processing rule applied to this document.", "type": "string" }, "disabled_at": { "description": "Timestamp when the document was disabled. `null` if enabled.", "nullable": true, "type": "number" }, "disabled_by": { "description": "ID of the user who disabled the document. `null` if enabled.", "nullable": true, "type": "string" }, "display_status": { "description": "User-facing display status derived from `indexing_status` and `enabled` state.", "type": "string" }, "doc_form": { "description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction.", "type": "string" }, "doc_metadata": { "description": "Metadata values assigned to this document.", "items": { "properties": { "id": { "description": "Metadata field identifier.", "type": "string" }, "name": { "description": "Metadata field name.", "type": "string" }, "type": { "description": "Metadata field value type.", "type": "string" }, "value": { "description": "Metadata value for this document.", "type": "string" } }, "type": "object" }, "type": "array" }, "enabled": { "description": "Whether the document is enabled for retrieval.", "type": "boolean" }, "error": { "description": "Error message if indexing failed. `null` when no error.", "nullable": true, "type": "string" }, "hit_count": { "description": "Number of times the document has been matched in retrieval queries.", "type": "integer" }, "id": { "description": "Unique identifier of the document.", "type": "string" }, "indexing_status": { "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.", "type": "string" }, "name": { "description": "Document name.", "type": "string" }, "need_summary": { "description": "Whether a summary needs to be generated for this document.", "type": "boolean" }, "position": { "description": "Display position of the document in the list.", "type": "integer" }, "summary_index_status": { "description": "Status of the summary index for this document. `null` if summary indexing is not configured.", "nullable": true, "type": "string" }, "tokens": { "description": "Total number of tokens in the document.", "type": "integer" }, "word_count": { "description": "Total word count of the document.", "type": "integer" } }, "type": "object" }, "EndUserDetail": { "properties": { "app_id": { "description": "Application ID.", "format": "uuid", "nullable": true, "type": "string" }, "created_at": { "description": "Creation timestamp.", "format": "date-time", "type": "string" }, "external_user_id": { "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)).", "nullable": true, "type": "string" }, "id": { "description": "End user ID.", "format": "uuid", "type": "string" }, "is_anonymous": { "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request.", "type": "boolean" }, "name": { "description": "End user name.", "nullable": true, "type": "string" }, "session_id": { "description": "Session identifier. Defaults to the `external_user_id` value.", "type": "string" }, "tenant_id": { "description": "Tenant ID.", "format": "uuid", "type": "string" }, "type": { "description": "End user type. Always `service-api` for Service API users.", "type": "string" }, "updated_at": { "description": "Last update timestamp.", "format": "date-time", "type": "string" } }, "type": "object" }, "EndUserSummary": { "properties": { "id": { "description": "End user ID.", "format": "uuid", "type": "string" }, "is_anonymous": { "description": "Whether the end user is anonymous.", "type": "boolean" }, "session_id": { "description": "Session identifier.", "type": "string" }, "type": { "description": "End user type.", "type": "string" } }, "type": "object" }, "FeedbackItem": { "description": "A single feedback item.", "properties": { "app_id": { "description": "Application ID.", "format": "uuid", "type": "string" }, "content": { "description": "Optional text feedback.", "nullable": true, "type": "string" }, "conversation_id": { "description": "Conversation ID.", "format": "uuid", "type": "string" }, "created_at": { "description": "Creation timestamp.", "format": "date-time", "type": "string" }, "from_account_id": { "description": "Account ID who submitted the feedback. Present when `from_source` is `admin`.", "format": "uuid", "nullable": true, "type": "string" }, "from_end_user_id": { "description": "End user ID who submitted the feedback. Present when `from_source` is `user`.", "format": "uuid", "nullable": true, "type": "string" }, "from_source": { "description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console.", "type": "string" }, "id": { "description": "Feedback ID.", "format": "uuid", "type": "string" }, "message_id": { "description": "Message ID.", "format": "uuid", "type": "string" }, "rating": { "description": "Feedback rating. `like` for positive, `dislike` for negative.", "type": "string" }, "updated_at": { "description": "Last update timestamp.", "format": "date-time", "type": "string" } }, "type": "object" }, "FileUploadResponse": { "properties": { "conversation_id": { "description": "ID of the associated conversation.", "format": "uuid", "nullable": true, "type": "string" }, "created_at": { "description": "Upload timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "created_by": { "description": "End-user ID of the uploader. Look up details with [Get End User Info](/en/api-reference/end-users/get-end-user-info).", "format": "uuid", "nullable": true, "type": "string" }, "extension": { "description": "File extension.", "nullable": true, "type": "string" }, "file_key": { "description": "Unused; always `null`.", "nullable": true, "type": "string" }, "id": { "description": "Unique file ID.", "format": "uuid", "type": "string" }, "mime_type": { "description": "MIME type of the file.", "nullable": true, "type": "string" }, "name": { "description": "File name.", "type": "string" }, "original_url": { "description": "Original URL of the file.", "nullable": true, "type": "string" }, "preview_url": { "description": "Preview URL for the file.", "nullable": true, "type": "string" }, "reference": { "description": "Opaque file reference used internally when attaching files in agent and tool contexts. Always `null` for files uploaded through this endpoint.", "nullable": true, "type": "string" }, "size": { "description": "File size in bytes.", "type": "integer" }, "source_url": { "description": "Signed URL for downloading the file.", "type": "string" }, "tenant_id": { "description": "ID of the associated tenant.", "format": "uuid", "nullable": true, "type": "string" }, "user_id": { "description": "Unused; always `null`.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "FormInput": { "description": "A form input field definition.", "properties": { "default": { "$ref": "#/components/schemas/FormInputDefault", "description": "Default value configuration for this input.", "nullable": true }, "output_variable_name": { "description": "Variable name where the input value is stored.", "type": "string" }, "type": { "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).", "type": "string" } }, "type": "object" }, "FormInputDefault": { "description": "Default value configuration for a form input.", "properties": { "selector": { "description": "Variable selector path when `type` is `variable`.", "items": { "type": "string" }, "type": "array" }, "type": { "description": "`variable` for dynamic values from workflow variables, `constant` for static values.", "type": "string" }, "value": { "description": "Static value when `type` is `constant`.", "type": "string" } }, "type": "object" }, "HumanInputContent": { "description": "Execution content from a Human Input node, including form definition and submission data.", "properties": { "form_definition": { "$ref": "#/components/schemas/HumanInputFormDefinition", "description": "Form definition from the Human Input node. `null` when the content represents a submission response.", "nullable": true }, "form_submission_data": { "$ref": "#/components/schemas/HumanInputFormSubmissionData", "description": "Submitted form data. `null` when the form has not been submitted yet.", "nullable": true }, "submitted": { "description": "Whether the human input form has been submitted.", "type": "boolean" }, "type": { "description": "`human_input` for human input content.", "type": "string" }, "workflow_run_id": { "description": "ID of the workflow run this content belongs to.", "type": "string" } }, "type": "object" }, "HumanInputFormDefinition": { "description": "Definition of a human input form rendered by a Human Input node.", "properties": { "actions": { "description": "Action buttons available on the form.", "items": { "$ref": "#/components/schemas/UserAction" }, "type": "array" }, "display_in_ui": { "description": "Whether the form should be displayed in the UI.", "type": "boolean" }, "expiration_time": { "description": "Unix timestamp when the form expires.", "type": "integer" }, "form_content": { "description": "Markdown or text content displayed with the form.", "type": "string" }, "form_id": { "description": "Unique form identifier.", "type": "string" }, "form_token": { "description": "Token for form submission authentication.", "nullable": true, "type": "string" }, "inputs": { "description": "Input fields in the form.", "items": { "$ref": "#/components/schemas/FormInput" }, "type": "array" }, "node_id": { "description": "ID of the Human Input node that generated this form.", "type": "string" }, "node_title": { "description": "Title of the Human Input node.", "type": "string" }, "resolved_default_values": { "additionalProperties": true, "description": "Resolved default values for form inputs, keyed by output variable name.", "type": "object" } }, "type": "object" }, "HumanInputFormSubmissionData": { "description": "Data from a submitted human input form.", "properties": { "action_id": { "description": "ID of the action button that was clicked.", "type": "string" }, "action_text": { "description": "Display text of the action button that was clicked.", "type": "string" }, "node_id": { "description": "ID of the Human Input node.", "type": "string" }, "node_title": { "description": "Title of the Human Input node.", "type": "string" }, "rendered_content": { "description": "Rendered content of the form submission.", "type": "string" } }, "type": "object" }, "InitialAnnotationReplySettingsRequest": { "description": "Request body for configuring annotation reply settings.", "properties": { "embedding_model_name": { "description": "Embedding model used to vectorize annotations for matching (for example, `text-embedding-3-small`).", "type": "string" }, "embedding_provider_name": { "description": "Embedding model provider (for example, `openai`). Get available providers from [Get Available Models](/en/api-reference/models/get-available-models).", "type": "string" }, "score_threshold": { "description": "Minimum similarity score for an annotation to be considered a match. Higher values require closer matches.", "format": "float", "type": "number" } }, "required": [ "score_threshold", "embedding_provider_name", "embedding_model_name" ], "type": "object" }, "InitialAnnotationReplySettingsResponse": { "properties": { "job_id": { "description": "Asynchronous job ID. Use with [Get Annotation Reply Job Status](/en/api-reference/annotations/get-annotation-reply-job-status) to track progress.", "format": "uuid", "type": "string" }, "job_status": { "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).", "type": "string" } }, "type": "object" }, "InitialAnnotationReplySettingsStatusResponse": { "properties": { "error_msg": { "description": "Error message describing why the job failed. Empty string when `job_status` is not `error`.", "type": "string" }, "job_id": { "description": "Job ID from the [Configure Annotation Reply](/en/api-reference/annotations/configure-annotation-reply) call.", "format": "uuid", "type": "string" }, "job_status": { "description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed.", "type": "string" } }, "type": "object" }, "InputFileObject": { "anyOf": [ { "not": { "required": [ "upload_file_id" ] }, "properties": { "transfer_method": { "enum": [ "remote_url" ] }, "url": { "format": "url", "type": "string" } }, "required": [ "url" ] }, { "not": { "required": [ "url" ] }, "properties": { "transfer_method": { "enum": [ "local_file" ] }, "upload_file_id": { "type": "string" } }, "required": [ "upload_file_id" ] } ], "properties": { "transfer_method": { "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file.", "enum": [ "remote_url", "local_file" ], "type": "string" }, "type": { "description": "File type.", "enum": [ "image", "document", "audio", "video", "custom" ], "type": "string" }, "upload_file_id": { "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`).", "type": "string" }, "url": { "description": "File URL (when `transfer_method` is `remote_url`).", "format": "url", "type": "string" } }, "required": [ "type", "transfer_method" ], "type": "object" }, "MessageFeedbackRequest": { "description": "Request body for submitting message feedback.", "properties": { "content": { "description": "Optional text feedback providing additional detail.", "type": "string" }, "rating": { "description": "Feedback rating. Set to `null` to revoke previously submitted feedback.", "enum": [ "like", "dislike", null ], "nullable": true, "type": "string" }, "user": { "description": "End-user identifier, defined by your app and unique within it. Must match the `user` that received the message, since feedback is scoped to that end user. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "required": [ "user" ], "type": "object" }, "MessageFileItem": { "description": "A file attached to a message.", "properties": { "belongs_to": { "description": "Who this file belongs to. `user` for user-uploaded files, `assistant` for assistant-generated files.", "nullable": true, "type": "string" }, "filename": { "description": "Original filename.", "type": "string" }, "id": { "description": "File ID.", "format": "uuid", "type": "string" }, "mime_type": { "description": "MIME type of the file.", "nullable": true, "type": "string" }, "size": { "description": "File size in bytes.", "nullable": true, "type": "integer" }, "transfer_method": { "description": "Transfer method used. `remote_url` for URL-based files, `local_file` for uploaded files, `tool_file` for tool-generated files.", "type": "string" }, "type": { "description": "File type, e.g., `image`.", "type": "string" }, "upload_file_id": { "description": "Upload file ID if transferred via `local_file`.", "format": "uuid", "nullable": true, "type": "string" }, "url": { "description": "Preview URL for the file.", "format": "url", "nullable": true, "type": "string" } }, "type": "object" }, "ParagraphControl": { "properties": { "default": { "description": "Default value pre-filled in the form field.", "type": "string" }, "label": { "description": "Display label for the form field.", "type": "string" }, "required": { "description": "Whether this field must be filled before submission.", "type": "boolean" }, "variable": { "description": "Variable name used as the key in the `inputs` object.", "type": "string" } }, "type": "object" }, "ParagraphControlWrapper": { "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } }, "title": "Paragraph", "type": "object" }, "RetrievalModel": { "properties": { "metadata_filtering_conditions": { "description": "Restrict retrieval to chunks whose document metadata matches the given conditions. Conditions are evaluated server-side against document metadata fields.", "nullable": true, "properties": { "conditions": { "description": "List of metadata conditions to evaluate.", "items": { "properties": { "comparison_operator": { "description": "Comparison to apply, by metadata type:\n\n- String or array metadata: `contains`, `not contains`, `start with`, `end with`, `is`, `is not`, `empty`, `not empty`, `in`, `not in`\n- Numeric metadata: `=`, `≠`, `>`, `<`, `≥`, `≤`\n- Time metadata: `before`, `after`", "enum": [ "contains", "not contains", "start with", "end with", "is", "is not", "empty", "not empty", "in", "not in", "=", "≠", ">", "<", "≥", "≤", "before", "after" ], "type": "string" }, "name": { "description": "Metadata field name to compare against.", "type": "string" }, "value": { "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`.", "nullable": true, "oneOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "number" } ] } }, "required": [ "name", "comparison_operator" ], "type": "object" }, "nullable": true, "type": "array" }, "logical_operator": { "default": "and", "description": "How to combine multiple conditions.", "enum": [ "and", "or" ], "nullable": true, "type": "string" } }, "type": "object" }, "reranking_enable": { "description": "Whether reranking is enabled.", "type": "boolean" }, "reranking_mode": { "description": "Reranking mode. Required when `reranking_enable` is `true`.", "enum": [ "reranking_model", "weighted_score" ], "nullable": true, "type": "string" }, "reranking_model": { "description": "Reranking model configuration.", "properties": { "reranking_model_name": { "description": "Name of the reranking model.", "type": "string" }, "reranking_provider_name": { "description": "Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). A bare name like `cohere` expands to `langgenius//` and works only for langgenius-published plugins.\n\nGet valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=rerank`.", "type": "string" } }, "type": "object" }, "score_threshold": { "description": "Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`.", "nullable": true, "type": "number" }, "score_threshold_enabled": { "description": "Whether score threshold filtering is enabled.", "type": "boolean" }, "search_method": { "description": "Search method used for retrieval.", "enum": [ "keyword_search", "semantic_search", "full_text_search", "hybrid_search" ], "type": "string" }, "top_k": { "description": "Maximum number of results to return.", "type": "integer" }, "weights": { "description": "Weight configuration for hybrid search.", "nullable": true, "properties": { "keyword_setting": { "description": "Keyword search weight settings.", "properties": { "keyword_weight": { "description": "Weight assigned to keyword search results.", "type": "number" } }, "type": "object" }, "vector_setting": { "description": "Semantic search weight settings.", "properties": { "embedding_model_name": { "description": "Name of the embedding model used for vector search.", "type": "string" }, "embedding_provider_name": { "description": "Provider of the embedding model used for vector search.", "type": "string" }, "vector_weight": { "description": "Weight assigned to semantic (vector) search results.", "type": "number" } }, "type": "object" }, "weight_type": { "description": "Strategy for balancing semantic and keyword search weights.", "enum": [ "semantic_first", "keyword_first", "customized" ], "type": "string" } }, "type": "object" } }, "required": [ "search_method", "reranking_enable", "top_k", "score_threshold_enabled" ], "type": "object" }, "RetrieverResource": { "description": "Citation and attribution information for a retriever resource.", "properties": { "content": { "description": "Content snippet from the resource.", "type": "string" }, "created_at": { "description": "Creation timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "data_source_type": { "description": "Type of the data source.", "type": "string" }, "dataset_id": { "description": "ID of the knowledge base.", "format": "uuid", "type": "string" }, "dataset_name": { "description": "Name of the knowledge base.", "type": "string" }, "document_id": { "description": "ID of the document.", "format": "uuid", "type": "string" }, "document_name": { "description": "Name of the document.", "type": "string" }, "hit_count": { "description": "Number of times this chunk was hit.", "type": "integer" }, "id": { "description": "Unique ID of the retriever resource.", "format": "uuid", "type": "string" }, "index_node_hash": { "description": "Hash of the index node.", "type": "string" }, "message_id": { "description": "ID of the message this resource belongs to.", "format": "uuid", "type": "string" }, "position": { "description": "Position of the resource in the list.", "type": "integer" }, "score": { "description": "Similarity score of the resource.", "format": "float", "type": "number" }, "segment_id": { "description": "ID of the specific chunk within the document.", "format": "uuid", "type": "string" }, "segment_position": { "description": "Position of the chunk within the document.", "type": "integer" }, "summary": { "description": "Summary of the chunk content.", "nullable": true, "type": "string" }, "word_count": { "description": "Word count of the chunk.", "type": "integer" } }, "type": "object" }, "Segment": { "properties": { "answer": { "description": "Answer content, used in Q&A mode documents.", "type": "string" }, "attachments": { "description": "Files attached to this chunk.", "items": { "properties": { "extension": { "description": "File extension.", "type": "string" }, "id": { "description": "Attachment file identifier.", "type": "string" }, "mime_type": { "description": "MIME type of the file.", "type": "string" }, "name": { "description": "Original file name.", "type": "string" }, "size": { "description": "File size in bytes.", "type": "integer" }, "source_url": { "description": "URL to access the attachment.", "type": "string" } }, "type": "object" }, "type": "array" }, "child_chunks": { "description": "Child chunks belonging to this chunk. Only present for hierarchical mode documents.", "items": { "$ref": "#/components/schemas/ChildChunk" }, "type": "array" }, "completed_at": { "description": "Timestamp when indexing completed. `null` if not yet completed.", "nullable": true, "type": "number" }, "content": { "description": "Text content of the chunk.", "type": "string" }, "created_at": { "description": "Creation timestamp (Unix epoch in seconds).", "type": "number" }, "created_by": { "description": "ID of the user who created the chunk.", "type": "string" }, "disabled_at": { "description": "Timestamp when the chunk was disabled. `null` if enabled.", "nullable": true, "type": "number" }, "disabled_by": { "description": "ID of the user who disabled the chunk. `null` if enabled.", "nullable": true, "type": "string" }, "document_id": { "description": "ID of the document this chunk belongs to.", "type": "string" }, "enabled": { "description": "Whether the chunk is enabled for retrieval.", "type": "boolean" }, "error": { "description": "Error message if indexing failed. `null` when no error.", "nullable": true, "type": "string" }, "hit_count": { "description": "Number of times this chunk has been matched in retrieval queries.", "type": "integer" }, "id": { "description": "Unique identifier of the chunk.", "type": "string" }, "index_node_hash": { "description": "Hash of the indexed content, used to detect changes.", "type": "string" }, "index_node_id": { "description": "ID of the index node in the vector store.", "type": "string" }, "indexing_at": { "description": "Timestamp when indexing started. `null` if not yet started.", "nullable": true, "type": "number" }, "keywords": { "description": "Keywords associated with this chunk for keyword-based retrieval.", "items": { "type": "string" }, "type": "array" }, "position": { "description": "Position of the chunk within the document.", "type": "integer" }, "sign_content": { "description": "Signed content hash for integrity verification.", "type": "string" }, "status": { "description": "Current indexing status of the chunk, e.g. `completed`, `indexing`, `error`.", "type": "string" }, "stopped_at": { "description": "Timestamp when indexing was stopped. `null` if not stopped.", "nullable": true, "type": "number" }, "summary": { "description": "AI-generated summary of the chunk content. `null` if summary indexing is not enabled.", "nullable": true, "type": "string" }, "tokens": { "description": "Token count of the chunk content.", "type": "integer" }, "updated_at": { "description": "Last update timestamp (Unix epoch in seconds).", "type": "number" }, "updated_by": { "description": "ID of the user who last updated the chunk.", "type": "string" }, "word_count": { "description": "Word count of the chunk content.", "type": "integer" } }, "type": "object" }, "SelectControl": { "properties": { "default": { "description": "Default selected value.", "type": "string" }, "label": { "description": "Display label for the form field.", "type": "string" }, "options": { "description": "List of selectable values for this form control.", "items": { "type": "string" }, "type": "array" }, "required": { "description": "Whether a selection must be made before submission.", "type": "boolean" }, "variable": { "description": "Variable name used as the key in the `inputs` object.", "type": "string" } }, "type": "object" }, "SelectControlWrapper": { "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } }, "title": "Select", "type": "object" }, "StreamEventAgentLog": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Agent log from an agent node within the workflow.", "properties": { "data": { "properties": { "data": { "additionalProperties": true, "description": "Log entry data.", "type": "object" }, "error": { "description": "Error message if applicable.", "nullable": true, "type": "string" }, "id": { "description": "Log entry ID.", "type": "string" }, "label": { "description": "Log entry label.", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Additional metadata.", "type": "object" }, "node_execution_id": { "description": "Node execution ID.", "type": "string" }, "node_id": { "description": "Node ID in the workflow graph.", "type": "string" }, "parent_id": { "description": "Parent log entry ID for nested entries.", "nullable": true, "type": "string" }, "status": { "description": "Log entry status.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "StreamEventBase": { "description": "Base properties for stream events.", "properties": { "conversation_id": { "description": "Conversation ID.", "format": "uuid", "type": "string" }, "created_at": { "description": "Creation timestamp.", "format": "int64", "type": "integer" }, "message_id": { "description": "Unique message ID.", "format": "uuid", "type": "string" }, "task_id": { "description": "Task ID.", "format": "uuid", "type": "string" } }, "type": "object" }, "StreamEventChatAgentMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "properties": { "answer": { "description": "LLM returned text chunk (Agent mode).", "type": "string" } }, "type": "object" } ] }, "StreamEventChatAgentThought": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Agent thought, LLM thinking, tool call details (Agent mode).", "properties": { "id": { "description": "Agent thought ID.", "format": "uuid", "type": "string" }, "message_files": { "description": "File IDs of files related to this thought.", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "observation": { "description": "Response from tool calls.", "type": "string" }, "position": { "description": "Position of this thought in the sequence for the message.", "type": "integer" }, "thought": { "description": "What LLM is thinking.", "type": "string" }, "tool": { "description": "List of tools called, split by `;`.", "type": "string" }, "tool_input": { "description": "Input of tools in JSON format.", "type": "string" } }, "type": "object" } ] }, "StreamEventChatError": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Error event during streaming.", "properties": { "code": { "description": "Error code.", "type": "string" }, "message": { "description": "Error message.", "type": "string" }, "status": { "description": "HTTP status code.", "type": "integer" } }, "type": "object" } ] }, "StreamEventChatMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "properties": { "answer": { "description": "LLM returned text chunk.", "type": "string" } }, "type": "object" } ] }, "StreamEventChatMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Message end event, streaming has ended.", "properties": { "id": { "description": "Unique message ID.", "format": "uuid", "type": "string" }, "metadata": { "description": "Metadata including usage and retriever resources.", "properties": { "retriever_resources": { "description": "List of retriever resources used.", "items": { "$ref": "#/components/schemas/RetrieverResource" }, "type": "array" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "type": "object" } }, "type": "object" } ] }, "StreamEventChatMessageFile": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Message file event, a new file created by a tool.", "properties": { "belongs_to": { "description": "Who this file belongs to. Always `assistant` for tool-generated files.", "type": "string" }, "id": { "description": "File unique ID.", "format": "uuid", "type": "string" }, "type": { "description": "File type, e.g. `image`.", "type": "string" }, "url": { "description": "Remote URL of the file.", "format": "url", "type": "string" } }, "type": "object" } ] }, "StreamEventChatMessageReplace": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Message content replacement event (e.g., due to content moderation).", "properties": { "answer": { "description": "Replacement content.", "type": "string" }, "reason": { "description": "Reason for the content replacement.", "type": "string" } }, "type": "object" } ] }, "StreamEventChatPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "description": "Ping event to keep connection alive. Delivered as an `event: ping` line with no `data:` payload. For Chatflow apps, a `ping` is also the first event of every stream.", "type": "object" } ] }, "StreamEventChatReasoningChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "properties": { "data": { "properties": { "is_final": { "description": "`true` marks the end of an LLM node's reasoning phase (the \"thinking finished\" signal); it may arrive with an empty `reasoning`.", "type": "boolean" }, "message_id": { "description": "ID of the message this reasoning belongs to (mirrors the top-level `message_id`).", "format": "uuid", "type": "string" }, "node_id": { "description": "ID of the LLM node producing the reasoning. Lets you attribute reasoning when multiple LLM nodes run.", "nullable": true, "type": "string" }, "reasoning": { "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.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "StreamEventChatTextChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "properties": { "data": { "properties": { "from_variable_selector": { "description": "Source path of the text variable in the workflow.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "text": { "description": "The text content chunk.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "StreamEventChatTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "TTS audio stream event (base64 encoded Mp3). Available if auto-play enabled.", "properties": { "audio": { "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file.", "format": "byte", "type": "string" } }, "type": "object" } ] }, "StreamEventChatTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "TTS audio stream end event.", "properties": { "audio": { "description": "Empty string. Signals the end of the audio stream.", "type": "string" } }, "type": "object" } ] }, "StreamEventError": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "code": { "description": "Error code.", "type": "string" }, "message": { "description": "Error message.", "type": "string" }, "status": { "description": "HTTP status code of the error.", "type": "integer" } }, "type": "object" } ] }, "StreamEventHumanInputFormFilled": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "properties": { "data": { "properties": { "action_id": { "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)).", "type": "string" }, "action_text": { "description": "Display text of the selected action.", "type": "string" }, "node_id": { "description": "ID of the Human Input node whose form was filled.", "type": "string" }, "node_title": { "description": "Display title of the Human Input node.", "type": "string" }, "rendered_content": { "description": "Form body rendered with the recipient's submitted values (`form_content` on `human_input_required` is the unfilled template).", "type": "string" }, "submitted_data": { "additionalProperties": true, "description": "Values the recipient submitted, keyed by each form input's `output_variable_name`.", "nullable": true, "type": "object" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventHumanInputFormTimeout": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "properties": { "data": { "properties": { "expiration_time": { "description": "Unix timestamp (seconds) when the form expired.", "format": "int64", "type": "integer" }, "node_id": { "description": "ID of the Human Input node whose form expired.", "type": "string" }, "node_title": { "description": "Display title of the Human Input node.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventHumanInputRequired": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "properties": { "data": { "properties": { "actions": { "description": "Available user actions (buttons) the recipient can select when submitting.", "items": { "properties": { "button_style": { "description": "Visual style of the button. Available values: `primary`, `default`, `accent`, `ghost`.", "type": "string" }, "id": { "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.", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "type": "string" }, "title": { "description": "Button label shown to the recipient.", "maxLength": 100, "type": "string" } }, "type": "object" }, "type": "array" }, "display_in_ui": { "description": "Whether the form is also shown in the Dify console UI.", "type": "boolean" }, "expiration_time": { "description": "Unix timestamp (seconds) after which the form can no longer be submitted.", "format": "int64", "type": "integer" }, "form_content": { "description": "Pre-rendered form body with workflow variables substituted.", "type": "string" }, "form_id": { "description": "Identifier for the form instance, surfaced in error messages and logs. Use `form_token` for Service API calls.", "type": "string" }, "form_token": { "description": "Access token for [Get Human Input Form](/en/api-reference/human-input/get-human-input-form) and [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form). `null` when the Human Input node uses Email or Console delivery (the Service API can only operate on web app-delivered forms).", "nullable": true, "type": "string" }, "inputs": { "description": "Form input fields the recipient fills in.", "items": { "properties": { "default": { "description": "Default value resolved from the workflow context. `null` when no default is configured.", "nullable": true, "properties": { "selector": { "description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements.", "items": { "type": "string" }, "type": "array" }, "type": { "description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable.", "type": "string" }, "value": { "description": "Literal default value when `type` is `constant`. Always a string.", "type": "string" } }, "type": "object" }, "output_variable_name": { "description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object.", "type": "string" }, "type": { "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).", "type": "string" } }, "type": "object" }, "type": "array" }, "node_id": { "description": "ID of the Human Input node that produced this form.", "type": "string" }, "node_title": { "description": "Display title of the Human Input node.", "type": "string" }, "resolved_default_values": { "additionalProperties": { "type": "string" }, "description": "Pre-filled default values for the form inputs, keyed by input `output_variable_name`. All values are stringified.", "type": "object" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventIterationCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Iteration loop completed.", "properties": { "data": { "properties": { "created_at": { "description": "Start timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Total iteration time in seconds.", "type": "number" }, "error": { "description": "Error message if iteration failed.", "nullable": true, "type": "string" }, "finished_at": { "description": "Finish timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "id": { "description": "Iteration execution ID.", "type": "string" }, "node_id": { "description": "Iteration node ID.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "outputs": { "additionalProperties": true, "description": "Iteration output data.", "nullable": true, "type": "object" }, "status": { "description": "Iteration execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred.", "type": "string" }, "steps": { "description": "Total number of iteration steps executed.", "type": "integer" }, "title": { "description": "Iteration node title.", "type": "string" }, "total_tokens": { "description": "Total tokens consumed across all iterations.", "type": "integer" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventIterationNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Iteration progressed to next item.", "properties": { "data": { "properties": { "created_at": { "description": "Timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "description": "Additional metadata.", "type": "object" }, "id": { "description": "Iteration execution ID.", "type": "string" }, "index": { "description": "Current iteration index (0-based).", "type": "integer" }, "node_id": { "description": "Iteration node ID.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "title": { "description": "Iteration node title.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventIterationStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Iteration loop started.", "properties": { "data": { "properties": { "created_at": { "description": "Start timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "description": "Additional metadata.", "type": "object" }, "id": { "description": "Iteration execution ID.", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Iteration input data.", "type": "object" }, "metadata": { "additionalProperties": true, "description": "Iteration metadata.", "type": "object" }, "node_id": { "description": "Iteration node ID.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "title": { "description": "Iteration node title.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventLoopCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Loop completed.", "properties": { "data": { "properties": { "created_at": { "description": "Start timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Total loop execution time in seconds.", "type": "number" }, "error": { "description": "Error message if loop failed.", "nullable": true, "type": "string" }, "finished_at": { "description": "Finish timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "id": { "description": "Loop execution ID.", "type": "string" }, "node_id": { "description": "Loop node ID.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "outputs": { "additionalProperties": true, "description": "Loop output data.", "nullable": true, "type": "object" }, "status": { "description": "Loop execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred.", "type": "string" }, "steps": { "description": "Total number of loop steps executed.", "type": "integer" }, "title": { "description": "Loop node title.", "type": "string" }, "total_tokens": { "description": "Total tokens consumed across all loop iterations.", "type": "integer" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventLoopNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Loop progressed to next iteration.", "properties": { "data": { "properties": { "created_at": { "description": "Timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "description": "Additional metadata.", "type": "object" }, "id": { "description": "Loop execution ID.", "type": "string" }, "index": { "description": "Current loop index (0-based).", "type": "integer" }, "node_id": { "description": "Loop node ID.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "pre_loop_output": { "description": "Output from the previous loop iteration." }, "title": { "description": "Loop node title.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventLoopStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Loop started.", "properties": { "data": { "properties": { "created_at": { "description": "Start timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "description": "Additional metadata.", "type": "object" }, "id": { "description": "Loop execution ID.", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Loop input data.", "type": "object" }, "metadata": { "additionalProperties": true, "description": "Loop metadata.", "type": "object" }, "node_id": { "description": "Loop node ID.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "title": { "description": "Loop node title.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "description": "LLM returns text chunk event.", "properties": { "answer": { "description": "LLM returned text chunk content.", "type": "string" } }, "type": "object" } ] }, "StreamEventMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "description": "Message end event, receiving this event means streaming has ended.", "properties": { "files": { "description": "Files generated during this message, such as model-generated images. `null` when no files were produced.", "items": { "properties": { "extension": { "description": "File extension, including the leading dot, e.g. `.png`.", "type": "string" }, "filename": { "description": "File name.", "type": "string" }, "mime_type": { "description": "MIME type of the file.", "type": "string" }, "related_id": { "description": "ID of the message file record.", "type": "string" }, "remote_url": { "description": "Original remote URL when the file was supplied as a remote URL; otherwise an empty string.", "nullable": true, "type": "string" }, "size": { "description": "File size in bytes.", "type": "integer" }, "transfer_method": { "description": "How the file is referenced: `remote_url`, `local_file`, or `tool_file`.", "type": "string" }, "type": { "description": "File type, e.g. `image`.", "type": "string" }, "upload_file_id": { "description": "ID of the associated uploaded file.", "type": "string" }, "url": { "description": "Accessible URL of the file.", "type": "string" } }, "type": "object" }, "nullable": true, "type": "array" }, "id": { "description": "Unique message ID.", "format": "uuid", "type": "string" }, "metadata": { "description": "Metadata including usage and retriever resources.", "properties": { "retriever_resources": { "description": "List of retriever resources used.", "items": { "$ref": "#/components/schemas/RetrieverResource" }, "type": "array" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "type": "object" } }, "type": "object" } ] }, "StreamEventMessageFile": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "description": "Message file event, a file (typically a model-generated image) produced during generation.", "properties": { "belongs_to": { "description": "Who this file belongs to, always `assistant` here.", "enum": [ "assistant" ], "type": "string" }, "id": { "description": "File unique ID.", "format": "uuid", "type": "string" }, "type": { "description": "File type, e.g. `image`.", "type": "string" }, "url": { "description": "Remote URL of the file.", "format": "url", "type": "string" } }, "type": "object" } ] }, "StreamEventMessageReplace": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "description": "Message content replacement event (e.g., due to content moderation).", "properties": { "answer": { "description": "Replacement content.", "type": "string" }, "reason": { "description": "Reason for the content replacement.", "type": "string" } }, "type": "object" } ] }, "StreamEventNodeFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Node execution finished.", "properties": { "data": { "properties": { "created_at": { "description": "Start timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Node execution time in seconds.", "type": "number" }, "error": { "description": "Error message if node failed.", "nullable": true, "type": "string" }, "execution_metadata": { "additionalProperties": true, "description": "Execution metadata (e.g., token usage, model info). May be `null` in simplified API responses.", "nullable": true, "type": "object" }, "files": { "description": "Files generated by this node.", "items": { "additionalProperties": true, "type": "object" }, "nullable": true, "type": "array" }, "finished_at": { "description": "Finish timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "id": { "description": "Node execution ID.", "type": "string" }, "index": { "description": "Execution index.", "type": "integer" }, "inputs": { "additionalProperties": true, "description": "Node input data. May be `null` in simplified API responses.", "nullable": true, "type": "object" }, "iteration_id": { "description": "Iteration ID if this node runs inside an iteration.", "nullable": true, "type": "string" }, "loop_id": { "description": "Loop ID if this node runs inside a loop.", "nullable": true, "type": "string" }, "node_id": { "description": "Node ID in the workflow graph.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "outputs": { "additionalProperties": true, "description": "Node output data. May be `null` in simplified API responses.", "nullable": true, "type": "object" }, "predecessor_node_id": { "description": "ID of the predecessor node.", "nullable": true, "type": "string" }, "process_data": { "additionalProperties": true, "description": "Node processing data. May be `null` in simplified API responses.", "nullable": true, "type": "object" }, "status": { "description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred.", "type": "string" }, "title": { "description": "Node title.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventNodeRetry": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Node retry attempt.", "properties": { "data": { "properties": { "created_at": { "description": "Start timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Execution time for this attempt in seconds.", "type": "number" }, "error": { "description": "Error message for this retry attempt.", "nullable": true, "type": "string" }, "execution_metadata": { "additionalProperties": true, "description": "Execution metadata.", "nullable": true, "type": "object" }, "files": { "description": "Files generated during this retry.", "items": { "additionalProperties": true, "type": "object" }, "nullable": true, "type": "array" }, "finished_at": { "description": "Finish timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "id": { "description": "Node execution ID.", "type": "string" }, "index": { "description": "Execution index.", "type": "integer" }, "inputs": { "additionalProperties": true, "description": "Node input data.", "nullable": true, "type": "object" }, "iteration_id": { "description": "Iteration ID if applicable.", "nullable": true, "type": "string" }, "loop_id": { "description": "Loop ID if applicable.", "nullable": true, "type": "string" }, "node_id": { "description": "Node ID in the workflow graph.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "outputs": { "additionalProperties": true, "description": "Node output data.", "nullable": true, "type": "object" }, "predecessor_node_id": { "description": "ID of the predecessor node.", "nullable": true, "type": "string" }, "process_data": { "additionalProperties": true, "description": "Node processing data.", "nullable": true, "type": "object" }, "retry_index": { "description": "Retry attempt index, starts at `0`.", "type": "integer" }, "status": { "description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred.", "type": "string" }, "title": { "description": "Node title.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventNodeStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Node execution started.", "properties": { "data": { "properties": { "created_at": { "description": "Start timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "description": "Additional metadata.", "type": "object" }, "id": { "description": "Node execution ID.", "type": "string" }, "index": { "description": "Execution index.", "type": "integer" }, "inputs": { "additionalProperties": true, "description": "Node input data. May be `null` in simplified API responses.", "nullable": true, "type": "object" }, "iteration_id": { "description": "Iteration ID if this node runs inside an iteration.", "nullable": true, "type": "string" }, "loop_id": { "description": "Loop ID if this node runs inside a loop.", "nullable": true, "type": "string" }, "node_id": { "description": "Node ID in the workflow graph.", "type": "string" }, "node_type": { "description": "Node type (e.g., `llm`, `knowledge-retrieval`, `code`).", "type": "string" }, "predecessor_node_id": { "description": "ID of the predecessor node.", "nullable": true, "type": "string" }, "title": { "description": "Node title.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "description": "Keep-alive ping event. Delivered as an `event: ping` line with no `data:` payload. The first event of every stream is a `ping`.", "type": "object" } ] }, "StreamEventReasoningChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "is_final": { "description": "`true` marks the end of an LLM node's reasoning phase (the \"thinking finished\" signal); it may arrive with an empty `reasoning`.", "type": "boolean" }, "node_id": { "description": "ID of the LLM node producing the reasoning. Lets you attribute reasoning when multiple LLM nodes run.", "nullable": true, "type": "string" }, "reasoning": { "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.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "StreamEventTextChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "from_variable_selector": { "description": "Source path of the text variable in the workflow.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "text": { "description": "The text content chunk.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "StreamEventTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "audio": { "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file.", "format": "byte", "type": "string" }, "created_at": { "description": "Unix timestamp of when this audio chunk was generated.", "format": "int64", "type": "integer" } }, "type": "object" } ] }, "StreamEventTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "audio": { "description": "Empty string. Signals the end of the audio stream.", "type": "string" }, "created_at": { "description": "Unix timestamp of when the audio stream ended.", "format": "int64", "type": "integer" } }, "type": "object" } ] }, "StreamEventWorkflowFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Workflow execution finished.", "properties": { "data": { "properties": { "created_at": { "description": "Start timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Total execution time in seconds.", "type": "number" }, "error": { "description": "Error message if execution failed.", "nullable": true, "type": "string" }, "exceptions_count": { "description": "Number of exceptions during execution.", "nullable": true, "type": "integer" }, "files": { "description": "Files generated during workflow execution.", "items": { "additionalProperties": true, "type": "object" }, "nullable": true, "type": "array" }, "finished_at": { "description": "Finish timestamp (Unix epoch seconds).", "format": "int64", "nullable": true, "type": "integer" }, "id": { "description": "Workflow run ID.", "type": "string" }, "outputs": { "additionalProperties": true, "description": "Workflow output data.", "nullable": true, "type": "object" }, "status": { "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.", "type": "string" }, "total_steps": { "description": "Total steps executed.", "type": "integer" }, "total_tokens": { "description": "Total tokens consumed.", "type": "integer" }, "workflow_id": { "description": "Associated workflow ID.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "StreamEventWorkflowPaused": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "description": "Creation timestamp.", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Total elapsed time in seconds.", "format": "float", "type": "number" }, "outputs": { "additionalProperties": true, "description": "Partial outputs at pause time.", "type": "object" }, "paused_nodes": { "description": "List of paused node IDs.", "items": { "type": "string" }, "type": "array" }, "reasons": { "description": "Reasons for pausing.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "status": { "description": "Workflow execution status.", "type": "string" }, "total_steps": { "description": "Total steps executed.", "type": "integer" }, "total_tokens": { "description": "Total tokens consumed.", "type": "integer" }, "workflow_run_id": { "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.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "StreamEventWorkflowStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "description": "Workflow execution started.", "properties": { "data": { "properties": { "created_at": { "description": "Start timestamp (Unix epoch seconds).", "format": "int64", "type": "integer" }, "id": { "description": "Workflow run ID.", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Input variables for this workflow execution.", "type": "object" }, "reason": { "description": "Reason for workflow start. `initial` for first start, `resumption` when resuming after a pause (e.g., after human input).", "type": "string" }, "workflow_id": { "description": "Associated workflow ID.", "type": "string" } }, "type": "object" }, "workflow_run_id": { "description": "Workflow execution run ID.", "type": "string" } }, "type": "object" } ] }, "SuggestedQuestionsResponse": { "properties": { "data": { "description": "List of suggested questions.", "items": { "type": "string" }, "type": "array" }, "result": { "description": "Result status.", "type": "string" } }, "type": "object" }, "TextInputControl": { "properties": { "default": { "description": "Default value pre-filled in the form field.", "type": "string" }, "label": { "description": "Display label for the form field.", "type": "string" }, "required": { "description": "Whether this field must be filled before submission.", "type": "boolean" }, "variable": { "description": "Variable name used as the key in the `inputs` object.", "type": "string" } }, "type": "object" }, "TextInputControlWrapper": { "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } }, "title": "Text Input", "type": "object" }, "TextToAudioRequest": { "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", "properties": { "message_id": { "description": "ID of the message whose answer to voice. Takes priority over `text` when both are provided. Get message IDs from [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages).", "format": "uuid", "type": "string" }, "streaming": { "description": "Accepted for backward compatibility but has no effect. Whether the audio is streamed is determined by the configured TTS provider's output, not by this field.", "type": "boolean" }, "text": { "description": "Text to synthesize into speech.", "type": "string" }, "user": { "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" }, "voice": { "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.", "type": "string" } }, "type": "object" }, "ToolIconDetail": { "description": "Detail of a tool icon using emoji.", "properties": { "background": { "description": "Background color in hex format.", "type": "string" }, "content": { "description": "Emoji content.", "type": "string" } }, "title": "Emoji Icon", "type": "object" }, "UpdateAnnotationRequest": { "description": "Request body for updating an annotation.", "properties": { "answer": { "description": "New answer text for the annotation.", "type": "string" }, "question": { "description": "New question text for the annotation.", "type": "string" } }, "required": [ "question", "answer" ], "type": "object" }, "Usage": { "description": "Model usage information.", "properties": { "completion_price": { "description": "Total price for completion tokens.", "format": "decimal", "type": "string" }, "completion_price_unit": { "description": "Price unit for completion tokens.", "format": "decimal", "type": "string" }, "completion_tokens": { "description": "Number of tokens in the completion.", "type": "integer" }, "completion_unit_price": { "description": "Unit price per completion token.", "format": "decimal", "type": "string" }, "currency": { "description": "Currency for pricing.", "type": "string" }, "latency": { "description": "Latency in seconds.", "format": "double", "type": "number" }, "prompt_price": { "description": "Total price for prompt tokens.", "format": "decimal", "type": "string" }, "prompt_price_unit": { "description": "Price unit for prompt tokens.", "format": "decimal", "type": "string" }, "prompt_tokens": { "description": "Number of tokens in the prompt.", "type": "integer" }, "prompt_unit_price": { "description": "Unit price per prompt token.", "format": "decimal", "type": "string" }, "total_price": { "description": "Total price for all tokens.", "format": "decimal", "type": "string" }, "total_tokens": { "description": "Total number of tokens used.", "type": "integer" } }, "type": "object" }, "UserAction": { "description": "An action button on a human input form.", "properties": { "button_style": { "description": "`primary`, `default`, `accent`, or `ghost`.", "type": "string" }, "id": { "description": "Unique action identifier.", "type": "string" }, "title": { "description": "Button display text.", "type": "string" } }, "type": "object" }, "UserInputFormItem": { "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapper" }, { "$ref": "#/components/schemas/ParagraphControlWrapper" }, { "$ref": "#/components/schemas/SelectControlWrapper" } ], "type": "object" }, "WebAppSettingsResponse": { "properties": { "chat_color_theme": { "description": "Chat color theme.", "type": "string" }, "chat_color_theme_inverted": { "description": "Whether the chat color theme is inverted.", "type": "boolean" }, "copyright": { "description": "Copyright text.", "type": "string" }, "custom_disclaimer": { "description": "Custom disclaimer text.", "type": "string" }, "default_language": { "description": "Default language code.", "type": "string" }, "description": { "description": "Web app description.", "type": "string" }, "icon": { "description": "Icon content (emoji or image ID).", "type": "string" }, "icon_background": { "description": "Icon background color.", "type": "string" }, "icon_type": { "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons.", "type": "string" }, "icon_url": { "description": "URL of the icon image.", "format": "url", "nullable": true, "type": "string" }, "input_placeholder": { "description": "Placeholder text shown in the web app message input box. `null` when not configured.", "nullable": true, "type": "string" }, "privacy_policy": { "description": "Privacy policy URL.", "type": "string" }, "show_workflow_steps": { "description": "Whether to show workflow steps.", "type": "boolean" }, "title": { "description": "Web app title.", "type": "string" }, "use_icon_as_answer_icon": { "description": "Whether to use the app icon as the answer icon.", "type": "boolean" } }, "type": "object" }, "WorkflowBlockingResponse": { "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedData" }, "task_id": { "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.", "format": "uuid", "type": "string" }, "workflow_run_id": { "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.", "format": "uuid", "type": "string" } }, "type": "object" }, "WorkflowExecutionRequest": { "properties": { "files": { "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`.", "items": { "$ref": "#/components/schemas/InputFileObject" }, "nullable": true, "type": "array" }, "inputs": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "items": { "$ref": "#/components/schemas/InputFileObject" }, "type": "array" } ] }, "description": "Key-value pairs for workflow input variables. Discover the variable names and types your app expects from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).\n\nFile-type variables take an array of file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`.", "type": "object" }, "response_mode": { "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.", "enum": [ "streaming", "blocking" ], "type": "string" }, "user": { "description": "End-user identifier, defined by your app and unique within it. Scopes data access: a workflow run and its files are only visible to later requests that carry the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "required": [ "inputs", "user" ], "type": "object" }, "WorkflowFinishedData": { "properties": { "created_at": { "description": "Unix timestamp of when the workflow run was created.", "format": "int64", "type": "integer" }, "created_by": { "additionalProperties": true, "description": "Creator information. Only present in streaming `workflow_finished` events.", "type": "object" }, "elapsed_time": { "description": "Total time elapsed in seconds.", "format": "float", "type": "number" }, "error": { "description": "Error message if the workflow failed.", "nullable": true, "type": "string" }, "exceptions_count": { "description": "Number of exceptions encountered during execution. Only present in streaming `workflow_finished` events.", "nullable": true, "type": "integer" }, "files": { "description": "Files generated during workflow execution. Only present in streaming `workflow_finished` events.", "items": { "additionalProperties": true, "type": "object" }, "nullable": true, "type": "array" }, "finished_at": { "description": "Unix timestamp of when the workflow run finished.", "format": "int64", "nullable": true, "type": "integer" }, "id": { "description": "Workflow run ID.", "format": "uuid", "type": "string" }, "outputs": { "additionalProperties": true, "description": "Output data from the workflow.", "nullable": true, "type": "object" }, "status": { "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.", "type": "string" }, "total_steps": { "description": "Total number of workflow steps executed.", "type": "integer" }, "total_tokens": { "description": "Total tokens consumed across all nodes.", "type": "integer" }, "workflow_id": { "description": "Workflow ID.", "format": "uuid", "type": "string" } }, "type": "object" }, "WorkflowLogItem": { "properties": { "created_at": { "description": "Unix timestamp of when the log entry was created.", "format": "int64", "type": "integer" }, "created_by_account": { "description": "Account details if created by an admin user.", "nullable": true, "properties": { "email": { "description": "Account email address.", "type": "string" }, "id": { "description": "Account ID.", "format": "uuid", "type": "string" }, "name": { "description": "Account display name.", "type": "string" } }, "type": "object" }, "created_by_end_user": { "$ref": "#/components/schemas/EndUserSummary" }, "created_by_role": { "description": "Role of the creator (e.g., `end_user`, `account`).", "type": "string" }, "created_from": { "description": "Source of the workflow run (e.g., `service-api`).", "type": "string" }, "details": { "additionalProperties": true, "description": "Additional details for the log entry.", "nullable": true, "type": "object" }, "id": { "description": "Log entry ID.", "format": "uuid", "type": "string" }, "workflow_run": { "$ref": "#/components/schemas/WorkflowRunSummary" } }, "type": "object" }, "WorkflowLogsResponse": { "properties": { "data": { "description": "List of workflow log entries.", "items": { "$ref": "#/components/schemas/WorkflowLogItem" }, "type": "array" }, "has_more": { "description": "Whether more pages are available.", "type": "boolean" }, "limit": { "description": "Number of items per page.", "type": "integer" }, "page": { "description": "Current page number.", "type": "integer" }, "total": { "description": "Total number of log entries.", "type": "integer" } }, "type": "object" }, "WorkflowRunDetailResponse": { "properties": { "created_at": { "description": "Unix timestamp of when the workflow run was created.", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Total time elapsed in seconds.", "format": "float", "nullable": true, "type": "number" }, "error": { "description": "Error message if the workflow failed.", "nullable": true, "type": "string" }, "finished_at": { "description": "Unix timestamp of when the workflow run finished.", "format": "int64", "nullable": true, "type": "integer" }, "id": { "description": "Workflow run ID.", "format": "uuid", "type": "string" }, "inputs": { "description": "Input variables of the workflow run, returned as a raw JSON string that clients must parse (e.g., `{\"query\": \"...\"}`). May be `null`.", "nullable": true, "type": "string" }, "outputs": { "additionalProperties": true, "description": "Output data from the workflow. An empty object until outputs are available.", "type": "object" }, "status": { "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.", "type": "string" }, "total_steps": { "description": "Total number of workflow steps executed.", "type": "integer" }, "total_tokens": { "description": "Total tokens consumed.", "type": "integer" }, "workflow_id": { "description": "Workflow ID.", "format": "uuid", "type": "string" } }, "type": "object" }, "WorkflowRunSummary": { "properties": { "created_at": { "description": "Unix timestamp of when the workflow run was created.", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Total time elapsed in seconds.", "format": "float", "type": "number" }, "error": { "description": "Error message if the workflow failed.", "nullable": true, "type": "string" }, "exceptions_count": { "description": "Number of exceptions that occurred during execution.", "type": "integer" }, "finished_at": { "description": "Unix timestamp of when the workflow run finished.", "format": "int64", "nullable": true, "type": "integer" }, "id": { "description": "Workflow run ID.", "format": "uuid", "type": "string" }, "status": { "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.", "type": "string" }, "total_steps": { "description": "Total number of workflow steps executed.", "type": "integer" }, "total_tokens": { "description": "Total tokens consumed.", "type": "integer" }, "triggered_from": { "description": "Source that triggered the workflow run. `app-run` for runs started from the app or API, `webhook` for runs started by a webhook trigger, `schedule` for runs started by a schedule trigger, `plugin` for runs started by an integration trigger.", "type": "string" }, "version": { "description": "Workflow version identifier.", "type": "string" } }, "type": "object" }, "WorkflowStreamEventAgentLog": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "data": { "additionalProperties": true, "description": "Agent step data.", "type": "object" }, "error": { "description": "Error message if the agent step failed.", "nullable": true, "type": "string" }, "id": { "description": "Agent log entry ID.", "type": "string" }, "label": { "description": "Log label.", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Agent step metadata.", "type": "object" }, "node_execution_id": { "description": "Node execution ID.", "type": "string" }, "node_id": { "description": "Node ID.", "type": "string" }, "parent_id": { "description": "Parent log entry ID.", "nullable": true, "type": "string" }, "status": { "description": "Agent step status.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventBase": { "properties": { "task_id": { "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.", "format": "uuid", "type": "string" }, "workflow_run_id": { "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.", "format": "uuid", "type": "string" } }, "type": "object" }, "WorkflowStreamEventHumanInputFormFilled": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "action_id": { "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)).", "type": "string" }, "action_text": { "description": "Display text of the selected action.", "type": "string" }, "node_id": { "description": "ID of the Human Input node whose form was filled.", "type": "string" }, "node_title": { "description": "Display title of the Human Input node.", "type": "string" }, "rendered_content": { "description": "Form body rendered with the recipient's submitted values (`form_content` on `human_input_required` is the unfilled template).", "type": "string" }, "submitted_data": { "additionalProperties": true, "description": "Values the recipient submitted, keyed by each form input's `output_variable_name`.", "nullable": true, "type": "object" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventHumanInputFormTimeout": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "expiration_time": { "description": "Unix timestamp (seconds) when the form expired.", "format": "int64", "type": "integer" }, "node_id": { "description": "ID of the Human Input node whose form expired.", "type": "string" }, "node_title": { "description": "Display title of the Human Input node.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventHumanInputRequired": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "actions": { "description": "Available user actions (buttons) the recipient can select when submitting.", "items": { "properties": { "button_style": { "description": "Visual style of the button. Available values: `primary`, `default`, `accent`, `ghost`.", "type": "string" }, "id": { "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.", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "type": "string" }, "title": { "description": "Button label shown to the recipient.", "maxLength": 100, "type": "string" } }, "type": "object" }, "type": "array" }, "display_in_ui": { "description": "Whether the form is also shown in the Dify console UI.", "type": "boolean" }, "expiration_time": { "description": "Unix timestamp (seconds) after which the form can no longer be submitted.", "format": "int64", "type": "integer" }, "form_content": { "description": "Pre-rendered form body with workflow variables substituted.", "type": "string" }, "form_id": { "description": "Identifier for the form instance, surfaced in error messages and logs. Use `form_token` for Service API calls.", "type": "string" }, "form_token": { "description": "Access token for [Get Human Input Form](/en/api-reference/human-input/get-human-input-form) and [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form). `null` when the Human Input node uses Email or Console delivery (the Service API can only operate on web app-delivered forms).", "nullable": true, "type": "string" }, "inputs": { "description": "Form input fields the recipient fills in.", "items": { "properties": { "default": { "description": "Default value resolved from the workflow context. `null` when no default is configured.", "nullable": true, "properties": { "selector": { "description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements.", "items": { "type": "string" }, "type": "array" }, "type": { "description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable.", "type": "string" }, "value": { "description": "Literal default value when `type` is `constant`. Always a string.", "type": "string" } }, "type": "object" }, "output_variable_name": { "description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object.", "type": "string" }, "type": { "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).", "type": "string" } }, "type": "object" }, "type": "array" }, "node_id": { "description": "ID of the Human Input node that produced this form.", "type": "string" }, "node_title": { "description": "Display title of the Human Input node.", "type": "string" }, "resolved_default_values": { "additionalProperties": { "type": "string" }, "description": "Pre-filled default values for the form inputs, keyed by input `output_variable_name`. All values are stringified.", "type": "object" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventIterationCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "description": "Unix timestamp of when the iteration started.", "format": "int64", "type": "integer" }, "elapsed_time": { "format": "float", "type": "number" }, "error": { "nullable": true, "type": "string" }, "execution_metadata": { "additionalProperties": true, "description": "Execution metadata including token usage.", "type": "object" }, "extras": { "additionalProperties": true, "description": "Additional metadata for the iteration.", "nullable": true, "type": "object" }, "finished_at": { "format": "int64", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Input variables for the iteration.", "nullable": true, "type": "object" }, "inputs_truncated": { "description": "Whether the `inputs` data was truncated.", "type": "boolean" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "outputs": { "additionalProperties": true, "nullable": true, "type": "object" }, "outputs_truncated": { "description": "Whether the `outputs` data was truncated.", "type": "boolean" }, "status": { "description": "Iteration completion status.", "type": "string" }, "steps": { "description": "Number of iteration steps completed.", "type": "integer" }, "title": { "type": "string" }, "total_tokens": { "type": "integer" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventIterationNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "type": "object" }, "id": { "format": "uuid", "type": "string" }, "index": { "description": "Current iteration index (zero-based).", "type": "integer" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventIterationStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "type": "object" }, "id": { "description": "Node execution ID.", "format": "uuid", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Input variables for the iteration.", "type": "object" }, "inputs_truncated": { "description": "Whether the `inputs` data was truncated.", "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Iteration metadata.", "type": "object" }, "node_id": { "description": "Iteration node ID.", "type": "string" }, "node_type": { "description": "Node type (always `iteration`).", "type": "string" }, "title": { "description": "Display name of the iteration node.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventLoopCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "format": "int64", "type": "integer" }, "elapsed_time": { "format": "float", "type": "number" }, "error": { "nullable": true, "type": "string" }, "execution_metadata": { "additionalProperties": true, "description": "Execution metadata including token usage.", "type": "object" }, "extras": { "additionalProperties": true, "description": "Additional metadata for the loop.", "nullable": true, "type": "object" }, "finished_at": { "format": "int64", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Input variables for the loop.", "nullable": true, "type": "object" }, "inputs_truncated": { "description": "Whether the `inputs` data was truncated.", "type": "boolean" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "outputs": { "additionalProperties": true, "nullable": true, "type": "object" }, "outputs_truncated": { "description": "Whether the `outputs` data was truncated.", "type": "boolean" }, "status": { "description": "Loop completion status.", "type": "string" }, "steps": { "description": "Number of loop iterations completed.", "type": "integer" }, "title": { "type": "string" }, "total_tokens": { "type": "integer" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventLoopNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "type": "object" }, "id": { "format": "uuid", "type": "string" }, "index": { "description": "Current loop iteration index (zero-based).", "type": "integer" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "pre_loop_output": { "description": "Output from the previous loop iteration.", "nullable": true }, "title": { "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventLoopStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "type": "object" }, "id": { "format": "uuid", "type": "string" }, "inputs": { "additionalProperties": true, "type": "object" }, "inputs_truncated": { "description": "Whether the `inputs` data was truncated.", "type": "boolean" }, "metadata": { "additionalProperties": true, "type": "object" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventNodeFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "description": "Unix timestamp of when the node execution started.", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Time elapsed in seconds.", "format": "float", "type": "number" }, "error": { "description": "Error message if the node failed.", "nullable": true, "type": "string" }, "execution_metadata": { "description": "Execution metadata including token usage.", "nullable": true, "properties": { "currency": { "description": "Currency of the cost (e.g., `USD`).", "nullable": true, "type": "string" }, "total_price": { "description": "Total cost for this node execution.", "format": "float", "nullable": true, "type": "number" }, "total_tokens": { "description": "Total tokens consumed by this node.", "nullable": true, "type": "integer" } }, "type": "object" }, "files": { "description": "Files generated by this node.", "items": { "additionalProperties": true, "type": "object" }, "nullable": true, "type": "array" }, "finished_at": { "description": "Unix timestamp of when the node execution finished.", "format": "int64", "type": "integer" }, "id": { "description": "Node execution ID.", "format": "uuid", "type": "string" }, "index": { "description": "Execution sequence index.", "type": "integer" }, "inputs": { "additionalProperties": true, "description": "Input variables for this node.", "nullable": true, "type": "object" }, "inputs_truncated": { "description": "Whether the `inputs` data was truncated.", "type": "boolean" }, "iteration_id": { "description": "Parent iteration ID if this node runs inside an iteration.", "nullable": true, "type": "string" }, "loop_id": { "description": "Parent loop ID if this node runs inside a loop.", "nullable": true, "type": "string" }, "node_id": { "description": "Node ID in the workflow graph.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "outputs": { "additionalProperties": true, "description": "Output data from the node.", "nullable": true, "type": "object" }, "outputs_truncated": { "description": "Whether the `outputs` data was truncated.", "type": "boolean" }, "predecessor_node_id": { "description": "ID of the predecessor node, if any.", "nullable": true, "type": "string" }, "process_data": { "additionalProperties": true, "description": "Processing data generated during node execution.", "nullable": true, "type": "object" }, "process_data_truncated": { "description": "Whether the `process_data` was truncated.", "type": "boolean" }, "status": { "description": "Node execution status. `running` for in-progress, `succeeded` when completed, `failed` on error, `stopped` when manually halted, `exception` on unexpected failure.", "type": "string" }, "title": { "description": "Display name of the node.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventNodeRetry": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Time elapsed in seconds.", "format": "float", "type": "number" }, "error": { "description": "Error message that triggered the retry.", "nullable": true, "type": "string" }, "execution_metadata": { "additionalProperties": true, "description": "Metadata from the node execution.", "nullable": true, "type": "object" }, "files": { "description": "Files produced by the node during execution.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "finished_at": { "format": "int64", "type": "integer" }, "id": { "description": "Node execution ID.", "format": "uuid", "type": "string" }, "index": { "description": "Execution sequence index.", "type": "integer" }, "inputs": { "additionalProperties": true, "nullable": true, "type": "object" }, "inputs_truncated": { "description": "Whether the `inputs` data was truncated.", "type": "boolean" }, "iteration_id": { "nullable": true, "type": "string" }, "loop_id": { "nullable": true, "type": "string" }, "node_id": { "description": "Node ID in the workflow graph.", "type": "string" }, "node_type": { "description": "Node type.", "type": "string" }, "outputs": { "additionalProperties": true, "nullable": true, "type": "object" }, "outputs_truncated": { "description": "Whether the `outputs` data was truncated.", "type": "boolean" }, "predecessor_node_id": { "description": "ID of the predecessor node, if any.", "nullable": true, "type": "string" }, "process_data": { "additionalProperties": true, "description": "Processing data generated during node execution.", "nullable": true, "type": "object" }, "process_data_truncated": { "description": "Whether the `process_data` was truncated.", "type": "boolean" }, "retry_index": { "description": "Zero-based retry attempt index.", "type": "integer" }, "status": { "description": "Node execution status at the retry point.", "type": "string" }, "title": { "description": "Display name of the node.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventNodeStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "description": "Unix timestamp of when the node execution started.", "format": "int64", "type": "integer" }, "extras": { "additionalProperties": true, "description": "Additional metadata for the node execution.", "type": "object" }, "id": { "description": "Node execution ID.", "format": "uuid", "type": "string" }, "index": { "description": "Execution sequence index.", "type": "integer" }, "inputs": { "additionalProperties": true, "description": "Input variables for this node.", "nullable": true, "type": "object" }, "inputs_truncated": { "description": "Whether the `inputs` data was truncated.", "type": "boolean" }, "iteration_id": { "description": "Parent iteration ID if this node runs inside an iteration.", "nullable": true, "type": "string" }, "loop_id": { "description": "Parent loop ID if this node runs inside a loop.", "nullable": true, "type": "string" }, "node_id": { "description": "Node ID in the workflow graph.", "type": "string" }, "node_type": { "description": "Node type (e.g., `llm`, `code`, `template-transform`).", "type": "string" }, "predecessor_node_id": { "description": "ID of the predecessor node, if any.", "nullable": true, "type": "string" }, "title": { "description": "Display name of the node.", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventWorkflowFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } }, "type": "object" } ] }, "WorkflowStreamEventWorkflowPaused": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "description": "Creation timestamp.", "format": "int64", "type": "integer" }, "elapsed_time": { "description": "Total elapsed time in seconds.", "format": "float", "type": "number" }, "outputs": { "additionalProperties": true, "description": "Partial outputs at pause time.", "type": "object" }, "paused_nodes": { "description": "List of paused node IDs.", "items": { "type": "string" }, "type": "array" }, "reasons": { "description": "Reasons for pausing.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "status": { "description": "Workflow execution status.", "type": "string" }, "total_steps": { "description": "Total steps executed.", "type": "integer" }, "total_tokens": { "description": "Total tokens consumed.", "type": "integer" }, "workflow_run_id": { "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.", "format": "uuid", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, "WorkflowStreamEventWorkflowStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "properties": { "data": { "properties": { "created_at": { "description": "Unix timestamp of when the workflow run started.", "format": "int64", "type": "integer" }, "id": { "description": "Workflow run ID.", "format": "uuid", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Input variables for this workflow run.", "type": "object" }, "reason": { "description": "Reason for the workflow start. `initial` for a new execution, `resumption` when resuming from a paused state.", "type": "string" }, "workflow_id": { "description": "Workflow ID.", "format": "uuid", "type": "string" } }, "type": "object" } }, "type": "object" } ] } }, "securitySchemes": { "ApiKeyAuth": { "bearerFormat": "API_KEY", "description": "Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)).\n\nKeep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`).", "scheme": "bearer", "type": "http" } } }, "info": { "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.", "title": "Dify Service API", "version": "1.0.0" }, "openapi": "3.0.1", "paths": { "/app/feedbacks": { "get": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns a paginated list of all feedback on the app's messages, including both end-user and admin submissions.", "operationId": "getChatAppFeedbacks", "parameters": [ { "description": "Page number.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Feedback items per page.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 101, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "feedbacksList": { "summary": "Response Example", "value": { "data": [ { "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "content": "The response accurately answered my question about product specifications.", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "created_at": "2025-01-16T14:30:29Z", "from_account_id": null, "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "from_source": "user", "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "rating": "like", "updated_at": "2025-01-16T14:30:29Z" }, { "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "content": "The answer was too vague and did not address the specific pricing question.", "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", "created_at": "2025-01-15T09:12:45Z", "from_account_id": null, "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", "from_source": "user", "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", "rating": "dislike", "updated_at": "2025-01-15T09:12:45Z" } ] } } }, "schema": { "$ref": "#/components/schemas/AppFeedbacksResponse" } } }, "description": "A list of application feedbacks." } }, "summary": "List App Feedbacks", "tags": [ "Feedback" ], "x-mint": { "href": "/en/api-reference/feedback/list-app-feedbacks", "metadata": { "sidebarTitle": "List App Feedbacks", "title": "List App Feedbacks" } } } }, "/apps/annotation-reply/{action}": { "post": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nEnables or disables annotation reply for the app. Runs asynchronously; track progress with [Get Annotation Reply Job Status](/en/api-reference/annotations/get-annotation-reply-job-status).\n\nThe body is validated before the action runs, so `score_threshold`, `embedding_provider_name`, and `embedding_model_name` are required even for `disable`.", "operationId": "initialAnnotationReplySettings", "parameters": [ { "description": "Whether to enable or disable annotation reply.", "in": "path", "name": "action", "required": true, "schema": { "enum": [ "enable", "disable" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "enableAnnotationReply": { "summary": "Request Example", "value": { "embedding_model_name": "text-embedding-3-small", "embedding_provider_name": "openai", "score_threshold": 0.9 } } }, "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "annotationReplyResponse": { "summary": "Response Example", "value": { "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "job_status": "waiting" } } }, "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" } } }, "description": "Annotation reply settings task initiated." } }, "summary": "Configure Annotation Reply", "tags": [ "Annotations" ], "x-mint": { "href": "/en/api-reference/annotations/configure-annotation-reply", "metadata": { "sidebarTitle": "Configure Annotation Reply", "title": "Configure Annotation Reply" } } } }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nReturns the status of an annotation reply configuration job started by [Configure Annotation Reply](/en/api-reference/annotations/configure-annotation-reply).", "operationId": "getInitialAnnotationReplySettingsStatus", "parameters": [ { "description": "Action type, must match the [Configure Annotation Reply](/en/api-reference/annotations/configure-annotation-reply) call.", "in": "path", "name": "action", "required": true, "schema": { "enum": [ "enable", "disable" ], "type": "string" } }, { "description": "Job ID returned by [Configure Annotation Reply](/en/api-reference/annotations/configure-annotation-reply).", "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "jobStatus": { "summary": "Response Example", "value": { "error_msg": "", "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "job_status": "completed" } } }, "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" } } }, "description": "Successfully retrieved task status." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "The job does not exist.", "status": 400 } } } } }, "description": "`invalid_param` : The specified job does not exist." } }, "summary": "Get Annotation Reply Job Status", "tags": [ "Annotations" ], "x-mint": { "href": "/en/api-reference/annotations/get-annotation-reply-job-status", "metadata": { "sidebarTitle": "Get Annotation Reply Job Status", "title": "Get Annotation Reply Job Status" } } } }, "/apps/annotations": { "get": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nLists the app's annotations, optionally filtered by keyword.", "operationId": "getAnnotationList", "parameters": [ { "description": "Page number.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Number of items per page. Requests above 100 are capped at 100.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "minimum": 1, "type": "integer" } }, { "description": "Keyword to filter annotations by question or answer content.", "in": "query", "name": "keyword", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "annotationList": { "summary": "Response Example", "value": { "data": [ { "answer": "Dify is an open-source LLM application development platform.", "created_at": 1705407629, "hit_count": 5, "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "question": "What is Dify?" } ], "has_more": false, "limit": 20, "page": 1, "total": 1 } } }, "schema": { "$ref": "#/components/schemas/AnnotationListResponse" } } }, "description": "Successfully retrieved annotation list." } }, "summary": "List Annotations", "tags": [ "Annotations" ], "x-mint": { "href": "/en/api-reference/annotations/list-annotations", "metadata": { "sidebarTitle": "List Annotations", "title": "List Annotations" } } }, "post": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nCreates an annotation. Annotations are predefined question-answer pairs the app returns directly on a match, instead of generating a fresh response.", "operationId": "createAnnotation", "requestBody": { "content": { "application/json": { "examples": { "createAnnotation": { "summary": "Request Example", "value": { "answer": "Dify is an open-source LLM application development platform.", "question": "What is Dify?" } } }, "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "createdAnnotation": { "summary": "Response Example", "value": { "answer": "Dify is an open-source LLM application development platform.", "created_at": 1705407629, "hit_count": 0, "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "question": "What is Dify?" } } }, "schema": { "$ref": "#/components/schemas/AnnotationItem" } } }, "description": "Annotation created successfully." } }, "summary": "Create Annotation", "tags": [ "Annotations" ], "x-mint": { "href": "/en/api-reference/annotations/create-annotation", "metadata": { "sidebarTitle": "Create Annotation", "title": "Create Annotation" } } } }, "/apps/annotations/{annotation_id}": { "delete": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nDeletes an annotation and its associated hit history.", "operationId": "deleteAnnotation", "parameters": [ { "description": "ID of the annotation to delete. Get annotation IDs from [List Annotations](/en/api-reference/annotations/list-annotations).", "in": "path", "name": "annotation_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Annotation deleted successfully." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Annotation not found", "status": 404 } } } } }, "description": "`not_found` : Annotation does not exist." } }, "summary": "Delete Annotation", "tags": [ "Annotations" ], "x-mint": { "href": "/en/api-reference/annotations/delete-annotation", "metadata": { "sidebarTitle": "Delete Annotation", "title": "Delete Annotation" } } }, "put": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nUpdates an annotation's question and answer.", "operationId": "updateAnnotation", "parameters": [ { "description": "ID of the annotation to update. Get annotation IDs from [List Annotations](/en/api-reference/annotations/list-annotations).", "in": "path", "name": "annotation_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "updateAnnotation": { "summary": "Request Example", "value": { "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", "question": "What is Dify?" } } }, "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "updatedAnnotation": { "summary": "Response Example", "value": { "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", "created_at": 1705407629, "hit_count": 5, "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "question": "What is Dify?" } } }, "schema": { "$ref": "#/components/schemas/AnnotationItem" } } }, "description": "Annotation updated successfully." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Annotation not found", "status": 404 } } } } }, "description": "`not_found` : Annotation does not exist." } }, "summary": "Update Annotation", "tags": [ "Annotations" ], "x-mint": { "href": "/en/api-reference/annotations/update-annotation", "metadata": { "sidebarTitle": "Update Annotation", "title": "Update Annotation" } } } }, "/audio-to-text": { "post": { "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nTranscribes an uploaded audio file to text using the workspace's default speech-to-text model.", "operationId": "audioToText", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "audioToTextSuccess": { "summary": "Response Example", "value": { "text": "Hello, I would like to know more about the iPhone 13 Pro Max." } } }, "schema": { "$ref": "#/components/schemas/AudioToTextResponse" } } }, "description": "Successfully converted audio to text." }, "400": { "content": { "application/json": { "examples": { "completion_request_error": { "summary": "completion_request_error", "value": { "code": "completion_request_error", "message": "Completion request failed.", "status": 400 } }, "no_audio_uploaded": { "summary": "no_audio_uploaded", "value": { "code": "no_audio_uploaded", "message": "Please upload your audio.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "provider_not_support_speech_to_text": { "summary": "provider_not_support_speech_to_text", "value": { "code": "provider_not_support_speech_to_text", "message": "Provider not support speech to text.", "status": 400 } }, "speech_to_text_disabled": { "summary": "speech_to_text_disabled", "value": { "code": "speech_to_text_disabled", "message": "Speech to text is disabled.", "status": 400 } } } } }, "description": "- `no_audio_uploaded` : No audio file was provided in the `file` field.\n- `speech_to_text_disabled` : Speech-to-text is disabled for this app.\n- `provider_not_support_speech_to_text` : The model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials are configured.\n- `completion_request_error` : The speech recognition request failed." }, "413": { "content": { "application/json": { "examples": { "audio_too_large": { "summary": "audio_too_large", "value": { "code": "audio_too_large", "message": "Audio size larger than 30 mb", "status": 413 } } } } }, "description": "`audio_too_large` : The audio file exceeds the `30 MB` size limit." }, "415": { "content": { "application/json": { "examples": { "unsupported_audio_type": { "summary": "unsupported_audio_type", "value": { "code": "unsupported_audio_type", "message": "Audio type not allowed.", "status": 415 } } } } }, "description": "`unsupported_audio_type` : The file's MIME type is not one of the accepted audio types (see the `file` field)." }, "500": { "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "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.", "status": 500 } } } } }, "description": "`internal_server_error` : Internal server error." } }, "summary": "Convert Audio to Text", "tags": [ "Audio" ], "x-mint": { "href": "/en/api-reference/audio/convert-audio-to-text", "metadata": { "sidebarTitle": "Convert Audio to Text", "title": "Convert Audio to Text" } } } }, "/chat-messages": { "post": { "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nSends a message to a chat app and returns the assistant's reply. The events in the streaming response vary by app type.", "operationId": "sendChatMessage", "requestBody": { "content": { "application/json": { "examples": { "blocking_example": { "summary": "Request Example - Blocking mode", "value": { "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "inputs": {}, "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "blocking", "user": "abc-123" } }, "streaming_example": { "summary": "Request Example - Streaming mode", "value": { "conversation_id": "", "files": [ { "transfer_method": "remote_url", "type": "image", "url": "https://cloud.dify.ai/logo/logo-site.png" } ], "inputs": { "city": "San Francisco" }, "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", "user": "abc-123" } } }, "schema": { "$ref": "#/components/schemas/ChatRequest" } } }, "description": "Request body to send a chat message.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "blockingResponse": { "summary": "Response Example - Blocking mode", "value": { "answer": "iPhone 13 Pro Max specs are listed here:...", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "created_at": 1705407629, "event": "message", "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "metadata": { "retriever_resources": [ { "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\"", "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", "dataset_name": "iPhone", "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", "document_name": "iPhone List", "position": 1, "score": 0.98457545, "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a" } ], "usage": { "completion_price": "0.0002560", "completion_price_unit": "0.001", "completion_tokens": 128, "completion_unit_price": "0.002", "currency": "USD", "latency": 0.7682376249867957, "prompt_price": "0.0010330", "prompt_price_unit": "0.001", "prompt_tokens": 1033, "prompt_unit_price": "0.001", "total_price": "0.0012890", "total_tokens": 1161 } }, "mode": "chat", "task_id": "c3800678-a077-43df-a102-53f23ed20b88" } } }, "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" } }, "text/event-stream": { "examples": { "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}}\n\ndata: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}}\n\ndata: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"paused_nodes\": [\"approval_node\"], \"outputs\": {}, \"reasons\": [{\"TYPE\": \"human_input_required\", \"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"resolved_default_values\": {\"comment\": \"\"}, \"form_token\": \"tok_abc123\", \"expiration_time\": 1705494029}], \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5, \"total_tokens\": 0, \"total_steps\": 1}}" }, "streamingResponseAgent": { "summary": "Response Example - Streaming (Agent)", "value": "data: {\"event\": \"agent_thought\", \"id\": \"agent_thought_id_1\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"position\": 1, \"thought\": \"Thinking about calling a tool...\", \"tool\": \"dalle3\", \"tool_input\": \"{\\\"dalle3\\\": {\\\"prompt\\\": \\\"a cute cat\\\"}}\", \"created_at\": 1705395332}\n\ndata: {\"event\": \"message_file\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"created_at\": 1705395332}\n\ndata: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333}\n\ndata: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}" }, "streamingResponseBasic": { "summary": "Response Example - Streaming (Basic)", "value": "data: {\"event\": \"message\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"created_at\": 1679586595, \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" }, "streamingResponseWorkflow": { "summary": "Response Example - Streaming (Workflow)", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"The user greeted me, so\", \"node_id\": \"node_llm_1\", \"is_final\": false}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}}\n\ndata: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333}\n\ndata: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395335, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}" } }, "schema": { "description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive; a Chatflow stream opens with one, then more arrive roughly every 10 seconds).\n\n**Events by app type** (the reply events, then how the stream closes):\n\n- **Chatbot**: `message` chunks (concatenate in order) → `message_end`.\n- **Legacy Agent**: `agent_thought` reasoning and tool-call steps alongside `agent_message` chunks → `message_end`.\n- **Agent**: `agent_message` chunks with `agent_thought` steps alongside → one closing `message` carrying the complete answer (treat it as the final answer, not extra text to append) → `message_end`. Its `message_end` metadata carries `usage` (plus `annotation_reply` on an annotation match) and never `retriever_resources`.\n- **Chatflow**: `workflow_started` → node events (`node_started`, `node_finished`, plus iteration and loop variants) alongside `message` chunks → then, by outcome:\n - **Success**: `message_end`, then `workflow_finished`\n - **Failure**: `workflow_finished` with status `failed`, then `error`; no `message_end`\n - **Pause**: `human_input_required`, then `workflow_paused` (the stream ends here; the run resumes separately)\n\n**Add-ons**:\n\n- Text-to-speech auto-play: `tts_message` audio chunks interleave, and `tts_message_end` trails the closing event.\n- Chatflow LLM nodes with `reasoning_format: separated` also emit `reasoning_chunk` deltas carrying the model's reasoning.\n\n**Common fields**: apart from `ping`, every event includes `conversation_id`, `message_id`, and `created_at` (Unix epoch seconds); all but `error` also include `task_id`. Workflow, node, and human-input events (Chatflow apps) nest their payload under `data` and, except for `agent_log`, carry a top-level `workflow_run_id`.\n\n**Reply events**\n\n| Event | App | Fires on | Key fields |\n|:---|:---|:---|:---|\n| `message` | Chatbot, Chatflow, Agent | each answer chunk (concatenate in order); for Agent, one closing chunk with the complete answer | `answer` |\n| `agent_message` | Legacy Agent, Agent | each answer chunk (concatenate in order) | `answer` |\n| `agent_thought` | Legacy Agent, Agent | each reasoning or tool-call step | `position`, `thought`, `tool`, `tool_input` (JSON), `observation`, `message_files` |\n| `message_replace` | All | output moderation replaces the answer so far | `answer`; Chatflow also `reason` |\n| `reasoning_chunk` | Chatflow | each reasoning-content delta, when an LLM node uses `reasoning_format: separated` (concatenate in order; a final `is_final: true` event marks reasoning finished and may carry an empty `reasoning`) | `data.message_id`, `data.reasoning`, `data.node_id`, `data.is_final` |\n| `message_file` | Chatbot, Legacy Agent | the assistant returns a file | `type`, `belongs_to`, `url` |\n| `message_end` | All | the answer is complete | `metadata` (`usage`, `retriever_resources`) |\n| `tts_message`, `tts_message_end` | Chatbot, Legacy Agent, Chatflow | audio chunk / end, when TTS auto-play is on | `audio` |\n\n**Workflow and node events** (Chatflow apps only)\n\nEach event nests its payload under a `data` object.\n\n| Event | Fires on | Key `data` fields |\n|:---|:---|:---|\n| `workflow_started` | the run begins | `inputs` |\n| `node_started` | a node begins | `node_id`, `node_type`, `title` |\n| `node_finished` | a node ends | `status`, `outputs`, `execution_metadata` |\n| `node_retry` | a node retries after a failure | `retry_index` |\n| `iteration_started`, `iteration_next`, `iteration_completed` | Iteration node progress (informational) | `data` |\n| `loop_started`, `loop_next`, `loop_completed` | Loop node progress (informational) | `data` |\n| `agent_log` | an Agent node step log (informational; no `workflow_run_id`) | `data` |\n| `workflow_finished` | the run ends | `status` (`succeeded`, `failed`, `partial-succeeded`, `stopped`), `outputs`, `total_tokens` |\n| `workflow_paused` | the run pauses | `paused_nodes`, `reasons` |\n| `human_input_required` | the run reaches a Human Input node | `form_token`, `form_content`, `expiration_time` |\n\nAfter a pause this stream ends at `workflow_paused`. Submit the form via [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form) or let it time out; the resumed run, including `human_input_form_filled`/`human_input_form_timeout` through `workflow_finished`, streams from [Stream Workflow Events](/en/api-reference/workflow-runs/stream-workflow-events).\n\n**Transport events**\n\n| Event | Fires on | Key fields |\n|:---|:---|:---|\n| `error` | a failure ends the stream; HTTP stays `200` | `status` (e.g. `400`), `code` (e.g. `invalid_param`), `message` |\n| `ping` | keep-alive; opens every Chatflow stream, then roughly every 10 seconds | none |", "type": "string" } } }, "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." }, "400": { "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "code": "app_unavailable", "message": "App unavailable, please check your app configurations.", "status": 400 } }, "completion_request_error": { "summary": "completion_request_error", "value": { "code": "completion_request_error", "message": "Completion request failed.", "status": 400 } }, "conversation_completed": { "summary": "conversation_completed", "value": { "code": "conversation_completed", "message": "The conversation has ended. Please start a new conversation.", "status": 400 } }, "is_draft_workflow": { "summary": "bad_request", "value": { "code": "bad_request", "message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. ", "status": 400 } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model.", "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 } }, "new_agent_streaming_only": { "summary": "bad_request", "value": { "code": "bad_request", "message": "Agent App only supports streaming response mode.", "status": 400 } }, "not_chat_app": { "summary": "not_chat_app", "value": { "code": "not_chat_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "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.", "status": 400 } }, "workflow_id_format_error": { "summary": "bad_request", "value": { "code": "bad_request", "message": "Invalid workflow_id format: 'not-a-valid-id'. ", "status": 400 } } } } }, "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `not_chat_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.\n- `bad_request` : Cannot use draft workflow version.\n- `bad_request` : Invalid `workflow_id` format.\n- `bad_request` : `blocking` response mode with an Agent app.\n- `invalid_param` : The Agent app has no bound Agent.\n- `agent_not_published` : The bound Agent has no published version. (Agent apps)\n- `conversation_completed` : The conversation has ended; start a new one by omitting `conversation_id`." }, "403": { "content": { "application/json": { "examples": { "workflow_version_execution_not_allowed": { "summary": "workflow_version_execution_not_allowed", "value": { "code": "workflow_version_execution_not_allowed", "message": "Workflow version execution is not available on your current plan. Please upgrade to a paid plan.", "status": 403 } } } } }, "description": "`workflow_version_execution_not_allowed` : A Chatflow request pinned a workflow version via `workflow_id` on the Dify Cloud Sandbox plan." }, "404": { "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Conversation Not Exists.", "status": 404 } }, "workflow_not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab", "status": 404 } } } } }, "description": "- `not_found` : Conversation does not exist.\n- `not_found` : Workflow not found with the specified `workflow_id`." }, "429": { "content": { "application/json": { "examples": { "rate_limit_error": { "summary": "rate_limit_error", "value": { "code": "rate_limit_error", "message": "Workflow execution quota limit reached for tenant 8f1e2a90-3b7c-4d55-9a01-6c2f4e8b1d33", "status": 429 } }, "too_many_requests": { "summary": "too_many_requests", "value": { "code": "too_many_requests", "message": "Too many requests. Please try again later.", "status": 429 } } } } }, "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached." }, "500": { "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "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.", "status": 500 } } } } }, "description": "`internal_server_error` : Internal server error." } }, "summary": "Send Chat Message", "tags": [ "Chat Messages" ], "x-mint": { "href": "/en/api-reference/chat-messages/send-chat-message", "metadata": { "sidebarTitle": "Send Chat Message", "title": "Send Chat Message" } } } }, "/chat-messages/{task_id}/stop": { "post": { "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nStops a chat message generation task. Only supported in `streaming` mode.", "operationId": "stopChatMessageGeneration", "parameters": [ { "description": "Task ID, from the streaming events of [Send Chat Message](/en/api-reference/chat-messages/send-chat-message).", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Request Example", "value": { "user": "abc-123" } } }, "schema": { "properties": { "user": { "description": "End-user identifier, defined by your app and unique within it. Must match the `user` sent with the original message; if it differs, the stop silently does nothing and still returns success. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "required": [ "user" ], "type": "object" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Arg user must be provided.", "status": 400 } }, "not_chat_app": { "summary": "not_chat_app", "value": { "code": "not_chat_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "- `not_chat_app` : App mode does not match the API route.\n- `invalid_param` : The required `user` field is missing." } }, "summary": "Stop Chat Message Generation", "tags": [ "Chat Messages" ], "x-mint": { "href": "/en/api-reference/chat-messages/stop-chat-message-generation", "metadata": { "sidebarTitle": "Stop Chat Message Generation", "title": "Stop Chat Message Generation" } } } }, "/completion-messages": { "post": { "description": "**Available for**: Text Generator apps.\n\nSends a request to a text-generation app and returns the generated text.", "operationId": "createCompletionMessage", "requestBody": { "content": { "application/json": { "examples": { "blocking_example": { "summary": "Request Example - Blocking mode", "value": { "inputs": { "city": "New York" }, "query": "Summarize the following text: ...", "response_mode": "blocking", "user": "def-456" } }, "streaming_example": { "summary": "Request Example - Streaming mode", "value": { "files": [ { "transfer_method": "remote_url", "type": "image", "url": "https://cloud.dify.ai/logo/logo-site.png" } ], "inputs": { "city": "San Francisco" }, "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", "user": "abc-123" } } }, "schema": { "$ref": "#/components/schemas/CompletionRequest" } } }, "description": "Request body to create a completion message.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "blockingResponse": { "summary": "Response Example - Blocking mode", "value": { "answer": "Hello World!...", "created_at": 1705407629, "event": "message", "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "metadata": { "usage": { "completion_price": "0.0002560", "completion_price_unit": "0.001", "completion_tokens": 128, "completion_unit_price": "0.002", "currency": "USD", "latency": 0.7682376249867957, "prompt_price": "0.0010330", "prompt_price_unit": "0.001", "prompt_tokens": 1033, "prompt_unit_price": "0.001", "total_price": "0.0012890", "total_tokens": 1161 } }, "mode": "completion", "task_id": "c3800678-a077-43df-a102-53f23ed20b88" } } }, "schema": { "$ref": "#/components/schemas/CompletionResponse" } }, "text/event-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" } }, "schema": { "description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive every 10 seconds). See `ChunkCompletionEvent` for the event structures.\n\n**Stream lifecycle**: the reply streams as `message` chunks and ends with `message_end`. An `error` event ends the stream early; HTTP status stays `200`, so inspect the event payload for details.", "type": "string" } } }, "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." }, "400": { "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "code": "app_unavailable", "message": "App unavailable, please check your app configurations.", "status": 400 } }, "completion_request_error": { "summary": "completion_request_error", "value": { "code": "completion_request_error", "message": "Completion request failed.", "status": 400 } }, "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Arg user must be provided.", "status": 400 } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "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.", "status": 400 } } } } }, "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.\n- `invalid_param` : The required `user` field is missing." }, "429": { "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "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.", "status": 429 } } } } }, "description": "`too_many_requests` : Too many concurrent requests for this app." }, "500": { "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "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.", "status": 500 } } } } }, "description": "`internal_server_error` : Internal server error." } }, "summary": "Send Completion Message", "tags": [ "Completion Messages" ], "x-mint": { "href": "/en/api-reference/completion-messages/send-completion-message", "metadata": { "sidebarTitle": "Send Completion Message", "title": "Send Completion Message" } } } }, "/completion-messages/{task_id}/stop": { "post": { "description": "**Available for**: Text Generator apps.\n\nStops a completion message generation task. Only supported in `streaming` mode.", "operationId": "stopGenerate", "parameters": [ { "description": "Task ID, from the streaming events of [Send Completion Message](/en/api-reference/completion-messages/send-completion-message).", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Request Example", "value": { "user": "abc-123" } } }, "schema": { "properties": { "user": { "description": "End-user identifier, defined by your app and unique within it. Must match the `user` sent with the original message; if it differs, the stop silently does nothing and still returns success. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "required": [ "user" ], "type": "object" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "code": "app_unavailable", "message": "App unavailable, please check your app configurations.", "status": 400 } }, "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Arg user must be provided.", "status": 400 } } } } }, "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `invalid_param` : The required `user` field is missing." } }, "summary": "Stop Completion Message Generation", "tags": [ "Completion Messages" ], "x-mint": { "href": "/en/api-reference/completion-messages/stop-completion-message-generation", "metadata": { "sidebarTitle": "Stop Completion Message Generation", "title": "Stop Completion Message Generation" } } } }, "/conversations": { "get": { "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nLists an end user's conversations, most recently active first.", "operationId": "getConversationsList", "parameters": [ { "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "in": "query", "name": "user", "required": false, "schema": { "type": "string" } }, { "description": "Pagination cursor: the `id` of the last conversation on the current page. Omit to fetch the first page.", "in": "query", "name": "last_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of records to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Field to sort by. Prefix with `-` for descending order.", "in": "query", "name": "sort_by", "required": false, "schema": { "default": "-updated_at", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "conversationsList": { "summary": "Response Example", "value": { "data": [ { "created_at": 1705407629, "id": "45701982-8118-4bc5-8e9b-64562b4555f2", "inputs": { "city": "San Francisco" }, "introduction": "Welcome! How can I help you today?", "name": "iPhone Specs Chat", "status": "normal", "updated_at": 1705411229 } ], "has_more": false, "limit": 20 } } }, "schema": { "$ref": "#/components/schemas/ConversationsListResponse" } } }, "description": "Successfully retrieved conversations list." }, "400": { "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "code": "not_chat_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "`not_chat_app` : App mode does not match the API route." }, "404": { "content": { "application/json": { "examples": { "last_conversation_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Last Conversation Not Exists.", "status": 404 } } } } }, "description": "`not_found` : Last conversation does not exist (invalid `last_id`)." } }, "summary": "List Conversations", "tags": [ "Conversations" ], "x-mint": { "href": "/en/api-reference/conversations/list-conversations", "metadata": { "sidebarTitle": "List Conversations", "title": "List Conversations" } } } }, "/conversations/{conversation_id}": { "delete": { "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nDeletes a conversation.", "operationId": "deleteConversation", "parameters": [ { "description": "ID of the conversation to delete. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "deleteExample": { "summary": "Request Example", "value": { "user": "abc-123" } } }, "schema": { "properties": { "user": { "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "type": "object" } } }, "description": "A JSON body is always required, even when `user` is omitted; send `{}` in that case.", "required": true }, "responses": { "204": { "description": "Conversation deleted successfully. No content returned." }, "400": { "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "code": "not_chat_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "`not_chat_app` : App mode does not match the API route." }, "404": { "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Conversation Not Exists.", "status": 404 } } } } }, "description": "`not_found` : Conversation does not exist." } }, "summary": "Delete Conversation", "tags": [ "Conversations" ], "x-mint": { "href": "/en/api-reference/conversations/delete-conversation", "metadata": { "sidebarTitle": "Delete Conversation", "title": "Delete Conversation" } } } }, "/conversations/{conversation_id}/name": { "post": { "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nRenames a conversation, or auto-generates a name from its messages when `auto_generate` is `true`. The name is what clients display in a multi-conversation list.", "operationId": "renameConversation", "parameters": [ { "description": "ID of the conversation to rename. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "renameExample": { "summary": "Request Example", "value": { "name": "iPhone Specs Chat", "user": "abc-123" } } }, "schema": { "$ref": "#/components/schemas/ConversationRenameRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "renamedConversation": { "summary": "Response Example", "value": { "created_at": 1705407629, "id": "45701982-8118-4bc5-8e9b-64562b4555f2", "inputs": { "city": "San Francisco" }, "introduction": "Welcome! How can I help you today?", "name": "iPhone Specs Chat", "status": "normal", "updated_at": 1705411229 } } }, "schema": { "$ref": "#/components/schemas/ConversationListItem" } } }, "description": "Conversation renamed successfully." }, "400": { "content": { "application/json": { "examples": { "no_messages": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "", "status": 400 } }, "not_chat_app": { "summary": "not_chat_app", "value": { "code": "not_chat_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "- `not_chat_app` : App mode does not match the API route.\n- `invalid_param` : `auto_generate` is `true` but the conversation has no messages to generate a name from." }, "404": { "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Conversation Not Exists.", "status": 404 } } } } }, "description": "`not_found` : Conversation does not exist." } }, "summary": "Rename Conversation", "tags": [ "Conversations" ], "x-mint": { "href": "/en/api-reference/conversations/rename-conversation", "metadata": { "sidebarTitle": "Rename Conversation", "title": "Rename Conversation" } } } }, "/conversations/{conversation_id}/variables": { "get": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nLists the variables stored in a conversation.", "operationId": "getConversationVariables", "parameters": [ { "description": "ID of the conversation whose variables to list. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } }, { "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "in": "query", "name": "user", "required": false, "schema": { "type": "string" } }, { "description": "Pagination cursor: the `id` of the last variable on the current page. Omit to fetch the first page.", "in": "query", "name": "last_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of records to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Filter variables by a specific name.", "in": "query", "name": "variable_name", "required": false, "schema": { "maxLength": 255, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "conversationVariables": { "summary": "Response Example", "value": { "data": [ { "created_at": 1705407629, "description": "User preference setting", "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "name": "user_preference", "updated_at": 1705411229, "value": "dark_mode", "value_type": "string" } ], "has_more": false, "limit": 20 } } }, "schema": { "$ref": "#/components/schemas/ConversationVariablesResponse" } } }, "description": "Successfully retrieved conversation variables." }, "400": { "content": { "application/json": { "examples": { "invalid_last_id": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "", "status": 400 } }, "not_chat_app": { "summary": "not_chat_app", "value": { "code": "not_chat_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "- `not_chat_app` : App mode does not match the API route.\n- `invalid_param` : The `last_id` does not match any variable in this conversation." }, "404": { "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Conversation Not Exists.", "status": 404 } } } } }, "description": "`not_found` : Conversation does not exist." } }, "summary": "List Conversation Variables", "tags": [ "Conversations" ], "x-mint": { "href": "/en/api-reference/conversations/list-conversation-variables", "metadata": { "sidebarTitle": "List Conversation Variables", "title": "List Conversation Variables" } } } }, "/conversations/{conversation_id}/variables/{variable_id}": { "put": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent apps.\n\nUpdates a conversation variable's value. The new value must match the variable's existing type.", "operationId": "updateChatConversationVariable", "parameters": [ { "description": "ID of the conversation that owns the variable. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "in": "path", "name": "conversation_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "ID of the variable to update. Get variable IDs from [List Conversation Variables](/en/api-reference/conversations/list-conversation-variables).", "in": "path", "name": "variable_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "updateStringVariable": { "summary": "Request Example", "value": { "user": "abc-123", "value": "new value" } } }, "schema": { "$ref": "#/components/schemas/ConversationVariableUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "updatedVariable": { "summary": "Response Example", "value": { "created_at": 1705407629, "description": "User preference setting", "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "name": "user_preference", "updated_at": 1705411229, "value": "new value", "value_type": "string" } } }, "schema": { "$ref": "#/components/schemas/ConversationVariableItem" } } }, "description": "Variable updated successfully." }, "400": { "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "code": "not_chat_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } }, "type_mismatch": { "summary": "bad_request", "value": { "code": "bad_request", "message": "Type mismatch: variable 'user_preference' expects string, but got number type", "status": 400 } } } } }, "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Variable value type mismatch." }, "404": { "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Conversation Not Exists.", "status": 404 } }, "variable_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Conversation Variable Not Exists.", "status": 404 } } } } }, "description": "- `not_found` : Conversation does not exist.\n- `not_found` : Conversation variable does not exist." } }, "summary": "Update Conversation Variable", "tags": [ "Conversations" ], "x-mint": { "href": "/en/api-reference/conversations/update-conversation-variable", "metadata": { "sidebarTitle": "Update Conversation Variable", "title": "Update Conversation Variable" } } } }, "/datasets": { "get": { "description": "Returns a paginated list of knowledge bases, optionally filtered by keyword or tags.", "operationId": "listDatasets", "parameters": [ { "description": "Page number.", "in": "query", "name": "page", "schema": { "default": 1, "type": "integer" } }, { "description": "Number of items per page. Server caps at `100`.", "in": "query", "name": "limit", "schema": { "default": 20, "type": "integer" } }, { "description": "Search keyword to filter by name.", "in": "query", "name": "keyword", "schema": { "type": "string" } }, { "description": "Whether to include all knowledge bases regardless of permissions.", "in": "query", "name": "include_all", "schema": { "default": false, "type": "boolean" } }, { "description": "Tag IDs to filter by. Get tag IDs from [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags).", "explode": true, "in": "query", "name": "tag_ids", "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "app_count": 0, "author_name": "admin", "built_in_field_enabled": true, "chunk_structure": null, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "data_source_type": null, "description": "Technical documentation for the product API", "doc_form": "text_model", "doc_metadata": [], "document_count": 0, "embedding_available": true, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "enable_api": true, "external_knowledge_info": null, "external_retrieval_model": null, "icon_info": null, "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "indexing_technique": "high_quality", "is_multimodal": false, "is_published": false, "maintainer": "admin", "name": "Product Documentation", "permission": "only_me", "pipeline_id": null, "provider": "vendor", "retrieval_model_dict": { "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_model_name": "", "reranking_provider_name": "" }, "score_threshold": null, "score_threshold_enabled": false, "search_method": "semantic_search", "top_k": 3, "weights": null }, "runtime_mode": null, "summary_index_setting": null, "tags": [], "total_available_documents": 0, "total_documents": 0, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "word_count": 0 } ], "has_more": false, "limit": 20, "page": 1, "total": 1 } } }, "schema": { "properties": { "data": { "description": "Array of knowledge base objects.", "items": { "$ref": "#/components/schemas/Dataset" }, "type": "array" }, "has_more": { "description": "Whether more items exist on the next page.", "type": "boolean" }, "limit": { "description": "Number of items per page.", "type": "integer" }, "page": { "description": "Current page number.", "type": "integer" }, "total": { "description": "Total number of matching items.", "type": "integer" } }, "type": "object" } } }, "description": "List of knowledge bases." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "`forbidden` : The API key is scoped to specific knowledge bases. This endpoint has no knowledge base ID in its path, so it requires a key with access to all knowledge bases." } }, "summary": "List Knowledge Bases", "tags": [ "Knowledge Bases" ], "x-mint": { "href": "/en/api-reference/knowledge-bases/list-knowledge-bases", "metadata": { "sidebarTitle": "List Knowledge Bases", "title": "List Knowledge Bases" } } }, "post": { "description": "Creates an empty knowledge base. Add documents to it with [Create Document by Text](/en/api-reference/documents/create-document-by-text) or [Create Document by File](/en/api-reference/documents/create-document-by-file).", "operationId": "createDataset", "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "default": "", "description": "Description of the knowledge base.", "maxLength": 400, "type": "string" }, "embedding_model": { "description": "Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.", "type": "string" }, "embedding_model_provider": { "description": "Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius//` and works only for langgenius-published plugins.\n\nGet valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.", "type": "string" }, "external_knowledge_api_id": { "description": "ID of the external knowledge API connection.", "type": "string" }, "external_knowledge_id": { "description": "ID of the external knowledge base.", "type": "string" }, "indexing_technique": { "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.", "enum": [ "high_quality", "economy" ], "nullable": true, "type": "string" }, "name": { "description": "Name of the knowledge base.", "maxLength": 40, "minLength": 1, "type": "string" }, "permission": { "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.", "enum": [ "only_me", "all_team_members", "partial_members" ], "type": "string" }, "provider": { "default": "vendor", "description": "`vendor` for internal knowledge base, `external` for external knowledge base.", "enum": [ "vendor", "external" ], "type": "string" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." }, "summary_index_setting": { "description": "Summary index configuration.", "nullable": true, "properties": { "enable": { "description": "Whether to enable summary indexing.", "type": "boolean" }, "model_name": { "description": "Name of the model used for generating summaries.", "type": "string" }, "model_provider_name": { "description": "Provider of the summary generation model.", "type": "string" }, "summary_prompt": { "description": "Custom prompt template for summary generation.", "type": "string" } }, "type": "object" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "app_count": 0, "author_name": "admin", "built_in_field_enabled": true, "chunk_structure": null, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "data_source_type": null, "description": "Technical documentation for the product API", "doc_form": "text_model", "doc_metadata": [], "document_count": 0, "embedding_available": true, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "enable_api": true, "external_knowledge_info": null, "external_retrieval_model": null, "icon_info": null, "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "indexing_technique": "high_quality", "is_multimodal": false, "is_published": false, "maintainer": "admin", "name": "Product Documentation", "permission": "only_me", "pipeline_id": null, "provider": "vendor", "retrieval_model_dict": { "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_model_name": "", "reranking_provider_name": "" }, "score_threshold": null, "score_threshold_enabled": false, "search_method": "semantic_search", "top_k": 3, "weights": null }, "runtime_mode": null, "summary_index_setting": null, "tags": [], "total_available_documents": 0, "total_documents": 0, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "word_count": 0 } } }, "schema": { "$ref": "#/components/schemas/Dataset" } } }, "description": "Knowledge base created successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.", "status": 400 } } } } }, "description": "`invalid_param` : The embedding or reranking model you specified is not configured or available." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Your subscription's knowledge base request rate limit has been reached.\n- `forbidden` : The API key is scoped to specific knowledge bases. This endpoint has no knowledge base ID in its path, so it requires a key with access to all knowledge bases." }, "409": { "content": { "application/json": { "examples": { "dataset_name_duplicate": { "summary": "dataset_name_duplicate", "value": { "code": "dataset_name_duplicate", "message": "The dataset name already exists. Please modify your dataset name.", "status": 409 } } } } }, "description": "`dataset_name_duplicate` : A knowledge base with the same name already exists." } }, "summary": "Create an Empty Knowledge Base", "tags": [ "Knowledge Bases" ], "x-mint": { "href": "/en/api-reference/knowledge-bases/create-an-empty-knowledge-base", "metadata": { "sidebarTitle": "Create an Empty Knowledge Base", "title": "Create an Empty Knowledge Base" } } } }, "/datasets/pipeline/file-upload": { "post": { "description": "Uploads a file for use in a knowledge pipeline. Use the returned `id` as the `reference` of a `local_file` item in [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline).", "operationId": "uploadPipelineFile", "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "The file to upload, as one `multipart/form-data` part. Document files are capped at 15 MB by default.\n\nSelf-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments).\n\nOn Dify Cloud, Professional and Team plans raise the document cap to 50 MB. Images, audio, and video follow their own limits: 10 MB, 50 MB, and 100 MB by default.", "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "created_at": "2025-03-06T12:00:00", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "extension": "pdf", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mime_type": "application/pdf", "name": "report.pdf", "size": 524288 } } }, "schema": { "properties": { "created_at": { "description": "Upload timestamp in ISO 8601 format. May be `null` while the record is being created.", "nullable": true, "type": "string" }, "created_by": { "description": "ID of the user who uploaded the file.", "type": "string" }, "extension": { "description": "File extension.", "type": "string" }, "id": { "description": "Unique identifier of the uploaded file.", "type": "string" }, "mime_type": { "description": "MIME type of the file. May be `null` if the upload did not include one.", "nullable": true, "type": "string" }, "name": { "description": "Original file name.", "type": "string" }, "size": { "description": "File size in bytes.", "type": "integer" } }, "type": "object" } } }, "description": "File uploaded successfully." }, "400": { "content": { "application/json": { "examples": { "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "code": "filename_not_exists_error", "message": "The specified filename does not exist.", "status": 400 } }, "no_file_uploaded": { "summary": "no_file_uploaded", "value": { "code": "no_file_uploaded", "message": "Please upload your file.", "status": 400 } }, "too_many_files": { "summary": "too_many_files", "value": { "code": "too_many_files", "message": "Only one file is allowed.", "status": 400 } } } } }, "description": "- `no_file_uploaded` : No file was provided in the request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `too_many_files` : Only one file is allowed per request." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "`forbidden` : The API key is scoped to specific knowledge bases. This endpoint has no knowledge base ID in its path, so it requires a key with access to all knowledge bases." }, "413": { "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "code": "file_too_large", "message": "File size exceeded.", "status": 413 } } } } }, "description": "`file_too_large` : The file exceeds the upload size limit." }, "415": { "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "code": "unsupported_file_type", "message": "File type not allowed.", "status": 415 } } } } }, "description": "`unsupported_file_type` : The file type is not supported." } }, "summary": "Upload Pipeline File", "tags": [ "Knowledge Pipeline" ], "x-mint": { "href": "/en/api-reference/knowledge-pipeline/upload-pipeline-file", "metadata": { "sidebarTitle": "Upload Pipeline File", "title": "Upload Pipeline File" } } } }, "/datasets/tags": { "delete": { "description": "Permanently delete a knowledge base tag. Does not delete the knowledge bases that were tagged.", "operationId": "deleteKnowledgeTag", "requestBody": { "content": { "application/json": { "schema": { "properties": { "tag_id": { "description": "ID of the tag to delete. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags).", "type": "string" } }, "required": [ "tag_id" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Success." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "`forbidden` : The API key is scoped to specific knowledge bases. This endpoint has no knowledge base ID in its path, so it requires a key with access to all knowledge bases." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Tag not found", "status": 404 } } } } }, "description": "`not_found` : The specified tag does not exist." } }, "summary": "Delete Knowledge Tag", "tags": [ "Tags" ], "x-mint": { "href": "/en/api-reference/tags/delete-knowledge-tag", "metadata": { "sidebarTitle": "Delete Knowledge Tag", "title": "Delete Knowledge Tag" } } }, "get": { "description": "Returns all knowledge base tags in the workspace.", "operationId": "getKnowledgeTags", "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": [ { "binding_count": "0", "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs", "type": "knowledge" } ] } }, "schema": { "items": { "properties": { "binding_count": { "description": "Number of knowledge bases bound to this tag.", "nullable": true, "type": "string" }, "id": { "description": "Tag identifier.", "type": "string" }, "name": { "description": "Tag display name.", "type": "string" }, "type": { "description": "Tag type. Always `knowledge` for knowledge base tags.", "type": "string" } }, "type": "object" }, "type": "array" } } }, "description": "List of tags." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "`forbidden` : The API key is scoped to specific knowledge bases. This endpoint has no knowledge base ID in its path, so it requires a key with access to all knowledge bases." } }, "summary": "List Knowledge Tags", "tags": [ "Tags" ], "x-mint": { "href": "/en/api-reference/tags/list-knowledge-tags", "metadata": { "sidebarTitle": "List Knowledge Tags", "title": "List Knowledge Tags" } } }, "patch": { "description": "Rename a knowledge base tag.", "operationId": "updateKnowledgeTag", "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "New name for the tag. Must be unique within the workspace.", "maxLength": 50, "minLength": 1, "type": "string" }, "tag_id": { "description": "ID of the tag to rename. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags).", "type": "string" } }, "required": [ "tag_id", "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "binding_count": "0", "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs", "type": "knowledge" } } }, "schema": { "properties": { "binding_count": { "description": "Number of knowledge bases bound to this tag.", "nullable": true, "type": "string" }, "id": { "description": "Tag identifier.", "type": "string" }, "name": { "description": "Tag display name.", "type": "string" }, "type": { "description": "Tag type. Always `knowledge` for knowledge base tags.", "type": "string" } }, "type": "object" } } }, "description": "Tag updated successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Tag name already exists", "status": 400 } } } } }, "description": "`invalid_param` : A knowledge tag with the same name already exists." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "`forbidden` : The API key is scoped to specific knowledge bases. This endpoint has no knowledge base ID in its path, so it requires a key with access to all knowledge bases." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Tag not found", "status": 404 } } } } }, "description": "`not_found` : The specified tag does not exist." } }, "summary": "Update Knowledge Tag", "tags": [ "Tags" ], "x-mint": { "href": "/en/api-reference/tags/update-knowledge-tag", "metadata": { "sidebarTitle": "Update Knowledge Tag", "title": "Update Knowledge Tag" } } }, "post": { "description": "Create a tag for organizing knowledge bases.", "operationId": "createKnowledgeTag", "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Tag name. Must be unique within the workspace.", "maxLength": 50, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "binding_count": "0", "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs", "type": "knowledge" } } }, "schema": { "properties": { "binding_count": { "description": "Number of knowledge bases bound to this tag.", "nullable": true, "type": "string" }, "id": { "description": "Tag identifier.", "type": "string" }, "name": { "description": "Tag display name.", "type": "string" }, "type": { "description": "Tag type. Always `knowledge` for knowledge base tags.", "type": "string" } }, "type": "object" } } }, "description": "Tag created successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Tag name already exists", "status": 400 } } } } }, "description": "`invalid_param` : A knowledge tag with the same name already exists." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "`forbidden` : The API key is scoped to specific knowledge bases. This endpoint has no knowledge base ID in its path, so it requires a key with access to all knowledge bases." } }, "summary": "Create Knowledge Tag", "tags": [ "Tags" ], "x-mint": { "href": "/en/api-reference/tags/create-knowledge-tag", "metadata": { "sidebarTitle": "Create Knowledge Tag", "title": "Create Knowledge Tag" } } } }, "/datasets/tags/binding": { "post": { "description": "Bind one or more tags to a knowledge base. A knowledge base can have multiple tags.", "operationId": "bindTagsToDataset", "requestBody": { "content": { "application/json": { "schema": { "properties": { "tag_ids": { "description": "IDs of the tags to bind. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags). Unknown tag IDs are silently ignored.", "items": { "type": "string" }, "minItems": 1, "type": "array" }, "target_id": { "description": "Knowledge base to bind the tags to. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).", "type": "string" } }, "required": [ "tag_ids", "target_id" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Success." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "`forbidden` : The API key is scoped to specific knowledge bases. Scope is checked only against a knowledge base ID in the path, not `target_id`, so this endpoint requires a key with access to all knowledge bases." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found", "status": 404 } } } } }, "description": "`not_found` : The target knowledge base does not exist." } }, "summary": "Create Tag Binding", "tags": [ "Tags" ], "x-mint": { "href": "/en/api-reference/tags/create-tag-binding", "metadata": { "sidebarTitle": "Create Tag Binding", "title": "Create Tag Binding" } } } }, "/datasets/tags/unbinding": { "post": { "description": "Remove one or more tags from a knowledge base.", "operationId": "unbindTagFromDataset", "requestBody": { "content": { "application/json": { "schema": { "properties": { "tag_id": { "deprecated": true, "description": "Legacy single-tag form. Normalized into `tag_ids` server-side. Use `tag_ids` for new integrations.", "type": "string" }, "tag_ids": { "description": "Tag IDs to unbind. Required unless the legacy `tag_id` is provided. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags).", "items": { "type": "string" }, "minItems": 1, "type": "array" }, "target_id": { "description": "Knowledge base to unbind the tags from. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).", "type": "string" } }, "required": [ "target_id" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Success." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "`forbidden` : The API key is scoped to specific knowledge bases. Scope is checked only against a knowledge base ID in the path, not `target_id`, so this endpoint requires a key with access to all knowledge bases." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found", "status": 404 } } } } }, "description": "`not_found` : The target knowledge base does not exist." } }, "summary": "Delete Tag Binding", "tags": [ "Tags" ], "x-mint": { "href": "/en/api-reference/tags/delete-tag-binding", "metadata": { "sidebarTitle": "Delete Tag Binding", "title": "Delete Tag Binding" } } } }, "/datasets/{dataset_id}": { "delete": { "description": "Permanently deletes a knowledge base, all of its documents, and any API key scoped only to it. Keys that also cover other knowledge bases keep working for those.", "operationId": "deleteDataset", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Knowledge base deleted successfully." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : Your subscription's knowledge base request rate limit has been reached.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : No knowledge base matches `dataset_id`." } }, "summary": "Delete Knowledge Base", "tags": [ "Knowledge Bases" ], "x-mint": { "href": "/en/api-reference/knowledge-bases/delete-knowledge-base", "metadata": { "sidebarTitle": "Delete Knowledge Base", "title": "Delete Knowledge Base" } } }, "get": { "description": "Returns detailed information about a knowledge base, including its embedding model, retrieval configuration, and document statistics.", "operationId": "getDatasetDetail", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "app_count": 0, "author_name": "admin", "built_in_field_enabled": true, "chunk_structure": null, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "data_source_type": null, "description": "Technical documentation for the product API", "doc_form": "text_model", "doc_metadata": [], "document_count": 0, "embedding_available": true, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "enable_api": true, "external_knowledge_info": null, "external_retrieval_model": null, "icon_info": null, "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "indexing_technique": "high_quality", "is_multimodal": false, "is_published": false, "maintainer": "admin", "name": "Product Documentation", "permission": "only_me", "pipeline_id": null, "provider": "vendor", "retrieval_model_dict": { "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_model_name": "", "reranking_provider_name": "" }, "score_threshold": null, "score_threshold_enabled": false, "search_method": "semantic_search", "top_k": 3, "weights": null }, "runtime_mode": null, "summary_index_setting": null, "tags": [], "total_available_documents": 0, "total_documents": 0, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "word_count": 0 } } }, "schema": { "$ref": "#/components/schemas/Dataset" } } }, "description": "Knowledge base details." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : No knowledge base matches `dataset_id`." } }, "summary": "Get Knowledge Base", "tags": [ "Knowledge Bases" ], "x-mint": { "href": "/en/api-reference/knowledge-bases/get-knowledge-base", "metadata": { "sidebarTitle": "Get Knowledge Base", "title": "Get Knowledge Base" } } }, "patch": { "description": "Updates a knowledge base. Only the fields included in the request body are changed.", "operationId": "updateDataset", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "Description of the knowledge base.", "maxLength": 400, "type": "string" }, "embedding_model": { "description": "Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.", "type": "string" }, "embedding_model_provider": { "description": "Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius//` and works only for langgenius-published plugins.\n\nGet valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.", "type": "string" }, "external_knowledge_api_id": { "description": "ID of the external knowledge API connection.", "type": "string" }, "external_knowledge_id": { "description": "ID of the external knowledge base.", "type": "string" }, "external_retrieval_model": { "description": "Retrieval settings for external knowledge bases.", "properties": { "score_threshold": { "description": "Minimum similarity score threshold for filtering results.", "type": "number" }, "score_threshold_enabled": { "description": "Whether score threshold filtering is enabled.", "type": "boolean" }, "top_k": { "description": "Maximum number of results to return.", "type": "integer" } }, "type": "object" }, "indexing_technique": { "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.", "enum": [ "high_quality", "economy" ], "nullable": true, "type": "string" }, "name": { "description": "Name of the knowledge base.", "maxLength": 40, "minLength": 1, "type": "string" }, "partial_member_list": { "description": "List of team members with access when `permission` is `partial_members`.", "items": { "properties": { "user_id": { "description": "ID of the team member to grant access.", "type": "string" } }, "type": "object" }, "type": "array" }, "permission": { "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.", "enum": [ "only_me", "all_team_members", "partial_members" ], "type": "string" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "app_count": 0, "author_name": "admin", "built_in_field_enabled": true, "chunk_structure": null, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "data_source_type": null, "description": "Technical documentation for the product API", "doc_form": "text_model", "doc_metadata": [], "document_count": 0, "embedding_available": true, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "enable_api": true, "external_knowledge_info": null, "external_retrieval_model": null, "icon_info": null, "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "indexing_technique": "high_quality", "is_multimodal": false, "is_published": false, "maintainer": "admin", "name": "Product Documentation", "partial_member_list": [], "permission": "only_me", "pipeline_id": null, "provider": "vendor", "retrieval_model_dict": { "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_model_name": "", "reranking_provider_name": "" }, "score_threshold": null, "score_threshold_enabled": false, "search_method": "semantic_search", "top_k": 3, "weights": null }, "runtime_mode": null, "summary_index_setting": null, "tags": [], "total_available_documents": 0, "total_documents": 0, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "word_count": 0 } } }, "schema": { "$ref": "#/components/schemas/Dataset" } } }, "description": "Knowledge base updated successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.", "status": 400 } } } } }, "description": "`invalid_param` : The embedding or reranking model you specified is not configured or available." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : Your subscription's knowledge base request rate limit has been reached.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : No knowledge base matches `dataset_id`." } }, "summary": "Update Knowledge Base", "tags": [ "Knowledge Bases" ], "x-mint": { "href": "/en/api-reference/knowledge-bases/update-knowledge-base", "metadata": { "sidebarTitle": "Update Knowledge Base", "title": "Update Knowledge Base" } } } }, "/datasets/{dataset_id}/document/create-by-file": { "post": { "description": "Creates a document in a knowledge base from an uploaded file. Common formats such as PDF, TXT, and DOCX are supported. Indexing runs asynchronously; track it with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).", "operationId": "createDocumentFromFile", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "data": { "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\"}}", "type": "string" }, "file": { "description": "File to upload, capped at 15 MB by default.\n\nSelf-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments). On Dify Cloud, Professional and Team plans raise the cap to 50 MB.", "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "batch": "20250306150245647595", "document": { "archived": false, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_from": "api", "data_source_detail_dict": { "upload_file": { "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "extension": "txt", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mime_type": "text/plain", "name": "guide.txt", "size": 2048 } }, "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_type": "upload_file", "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "disabled_at": null, "disabled_by": null, "display_status": "indexing", "doc_form": "text_model", "doc_metadata": [], "enabled": true, "error": null, "hit_count": 0, "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_status": "indexing", "name": "guide.txt", "need_summary": false, "position": 1, "summary_index_status": null, "tokens": 0, "word_count": 0 } } } }, "schema": { "properties": { "batch": { "description": "Batch ID for tracking indexing progress.", "type": "string" }, "document": { "$ref": "#/components/schemas/Document" } }, "type": "object" } } }, "description": "Document created successfully." }, "400": { "content": { "application/json": { "examples": { "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "code": "filename_not_exists_error", "message": "The specified filename does not exist.", "status": 400 } }, "invalid_param_external": { "summary": "invalid_param (external)", "value": { "code": "invalid_param", "message": "External datasets are not supported.", "status": 400 } }, "no_file_uploaded": { "summary": "no_file_uploaded", "value": { "code": "no_file_uploaded", "message": "Please upload your file.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "too_many_files": { "summary": "too_many_files", "value": { "code": "too_many_files", "message": "Only one file is allowed.", "status": 400 } } } } }, "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : The knowledge base is external, `indexing_technique` is required, or `process_rule` is missing." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (documents limit)", "value": { "code": "forbidden", "message": "The number of documents has reached the limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_5": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : The number of documents has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Knowledge base not found." }, "413": { "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "code": "file_too_large", "message": "File size exceeded.", "status": 413 } } } } }, "description": "`file_too_large` : The uploaded file exceeds the maximum size." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later.", "status": 503 } } } } }, "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later." } }, "summary": "Create Document by File", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/create-document-by-file", "metadata": { "sidebarTitle": "Create Document by File", "title": "Create Document by File" } } } }, "/datasets/{dataset_id}/document/create-by-text": { "post": { "description": "Creates a document in a knowledge base from raw text. Indexing runs asynchronously; track it with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).", "operationId": "createDocumentFromText", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "text_document": { "summary": "Request Example", "value": { "indexing_technique": "high_quality", "name": "guide.txt", "text": "Dify is an open-source LLM application development platform. This guide covers building AI applications with workflows, RAG pipelines, and agents." } } }, "schema": { "properties": { "doc_form": { "default": "text_model", "description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction.", "enum": [ "text_model", "hierarchical_model", "qa_model" ], "type": "string" }, "doc_language": { "default": "English", "description": "Language of the document for processing optimization.", "type": "string" }, "embedding_model": { "description": "Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.", "type": "string" }, "embedding_model_provider": { "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.", "type": "string" }, "indexing_technique": { "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.", "enum": [ "high_quality", "economy" ], "type": "string" }, "name": { "description": "Document name.", "type": "string" }, "original_document_id": { "description": "Original document ID for versioning. Get it from [List Documents](/en/api-reference/documents/list-documents).", "type": "string" }, "process_rule": { "description": "Processing rules for chunking.", "properties": { "mode": { "description": "`automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`).", "enum": [ "automatic", "custom", "hierarchical" ], "type": "string" }, "rules": { "properties": { "pre_processing_rules": { "items": { "properties": { "enabled": { "description": "Whether this preprocessing rule is enabled.", "type": "boolean" }, "id": { "description": "Rule identifier.", "enum": [ "remove_stopwords", "remove_extra_spaces", "remove_urls_emails" ], "type": "string" } }, "type": "object" }, "type": "array" }, "segmentation": { "properties": { "chunk_overlap": { "default": 0, "description": "Token overlap between chunks.", "type": "integer" }, "max_tokens": { "description": "Maximum token count per chunk.", "type": "integer" }, "separator": { "default": "\n", "description": "Custom separator for splitting text.", "type": "string" } }, "type": "object" } }, "type": "object" } }, "required": [ "mode" ], "type": "object" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Controls how chunks are searched and ranked when querying this knowledge base." }, "text": { "description": "Document text content.", "type": "string" } }, "required": [ "name", "text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "batch": "20250306150245647595", "document": { "archived": false, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_from": "api", "data_source_detail_dict": { "upload_file": { "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "extension": "txt", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mime_type": "text/plain", "name": "guide.txt", "size": 2048 } }, "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_type": "upload_file", "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "disabled_at": null, "disabled_by": null, "display_status": "indexing", "doc_form": "text_model", "doc_metadata": [], "enabled": true, "error": null, "hit_count": 0, "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_status": "indexing", "name": "guide.txt", "need_summary": false, "position": 1, "summary_index_status": null, "tokens": 0, "word_count": 0 } } } }, "schema": { "properties": { "batch": { "description": "Batch ID for tracking indexing progress.", "type": "string" }, "document": { "$ref": "#/components/schemas/Document" } }, "type": "object" } } }, "description": "Document created successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param_indexing": { "summary": "invalid_param (indexing_technique)", "value": { "code": "invalid_param", "message": "indexing_technique is required.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } } } } }, "description": "- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : `indexing_technique` is required when adding the first document, or `doc_form` is invalid." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (documents limit)", "value": { "code": "forbidden", "message": "The number of documents has reached the limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_5": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : The number of documents has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Knowledge base not found." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later.", "status": 503 } } } } }, "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later." } }, "summary": "Create Document by Text", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/create-document-by-text", "metadata": { "sidebarTitle": "Create Document by Text", "title": "Create Document by Text" } } } }, "/datasets/{dataset_id}/documents": { "get": { "description": "Returns a paginated list of documents in a knowledge base.", "operationId": "listDocuments", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Page number.", "in": "query", "name": "page", "schema": { "default": 1, "type": "integer" } }, { "description": "Number of items per page. Server caps at `100`.", "in": "query", "name": "limit", "schema": { "default": 20, "type": "integer" } }, { "description": "Search keyword to filter by document name.", "in": "query", "name": "keyword", "schema": { "type": "string" } }, { "description": "Filter by display status.", "in": "query", "name": "status", "schema": { "enum": [ "queuing", "indexing", "paused", "error", "available", "disabled", "archived" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "archived": false, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_from": "api", "data_source_detail_dict": { "upload_file": { "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "extension": "txt", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mime_type": "text/plain", "name": "guide.txt", "size": 2048 } }, "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_type": "upload_file", "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "disabled_at": null, "disabled_by": null, "display_status": "available", "doc_form": "text_model", "doc_metadata": [], "enabled": true, "error": null, "hit_count": 0, "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_status": "completed", "name": "guide.txt", "need_summary": false, "position": 1, "summary_index_status": null, "tokens": 512, "word_count": 350 } ], "has_more": false, "limit": 20, "page": 1, "total": 1 } } }, "schema": { "properties": { "data": { "description": "Array of document objects.", "items": { "$ref": "#/components/schemas/Document" }, "type": "array" }, "has_more": { "description": "Whether more items exist on the next page.", "type": "boolean" }, "limit": { "description": "Number of items per page.", "type": "integer" }, "page": { "description": "Current page number.", "type": "integer" }, "total": { "description": "Total number of matching items.", "type": "integer" } }, "type": "object" } } }, "description": "List of documents." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Knowledge base not found." } }, "summary": "List Documents", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/list-documents", "metadata": { "sidebarTitle": "List Documents", "title": "List Documents" } } } }, "/datasets/{dataset_id}/documents/download-zip": { "post": { "description": "Downloads one or more documents as a single ZIP archive. Only documents that were uploaded as files can be included.", "operationId": "downloadDocumentsZip", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "document_ids": { "description": "Document IDs to include in the archive. Get them from [List Documents](/en/api-reference/documents/list-documents).", "items": { "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "document_ids" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/zip": { "schema": { "description": "ZIP archive binary stream.", "format": "binary", "type": "string" } } }, "description": "ZIP archive containing the requested documents." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (dataset permission)", "value": { "code": "forbidden", "message": "You do not have permission to access this dataset.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (document permission)", "value": { "code": "forbidden", "message": "No permission.", "status": 403 } }, "forbidden_5": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : You do not have permission to access this knowledge base.\n- `forbidden` : You do not have permission for one of the requested documents.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_3": { "summary": "not_found_3", "value": { "code": "not_found", "message": "Only uploaded-file documents can be downloaded as ZIP.", "status": 404 } } } } }, "description": "- `not_found` : Document not found.\n- `not_found` : Knowledge base not found. Also returned as \"Only uploaded-file documents can be downloaded as ZIP.\" when a requested document has no uploaded file." } }, "summary": "Download Documents as ZIP", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/download-documents-as-zip", "metadata": { "sidebarTitle": "Download Documents as ZIP", "title": "Download Documents as ZIP" } } } }, "/datasets/{dataset_id}/documents/metadata": { "post": { "description": "Update metadata values for multiple documents in a single request.", "operationId": "batchUpdateDocumentMetadata", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "operation_data": { "description": "Document metadata update operations, one entry per document.", "items": { "properties": { "document_id": { "description": "ID of the document to update. See [List Documents](/en/api-reference/documents/list-documents).", "type": "string" }, "metadata_list": { "description": "Metadata fields to set on the document.", "items": { "properties": { "id": { "description": "Metadata field ID. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields).", "type": "string" }, "name": { "description": "Metadata field name.", "type": "string" }, "value": { "description": "Metadata value. Can be a string, number, or `null`." } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "partial_update": { "default": false, "description": "Whether to partially update metadata, keeping existing values for unspecified fields.", "type": "boolean" } }, "required": [ "document_id", "metadata_list" ], "type": "object" }, "type": "array" } }, "required": [ "operation_data" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "result": "success" } } }, "schema": { "properties": { "result": { "description": "Operation result.", "type": "string" } }, "type": "object" } } }, "description": "Document metadata updated successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Another document metadata operation is running, please wait a moment.", "status": 400 } } } } }, "description": "`invalid_param` : Another metadata operation is already running for a document in this request." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found (knowledge base)", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found (document)", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_3": { "summary": "not_found (metadata)", "value": { "code": "not_found", "message": "Metadata not found.", "status": 404 } } } } }, "description": "- `not_found` : Knowledge base not found.\n- `not_found` : A document referenced in `operation_data` does not exist in this knowledge base.\n- `not_found` : A metadata field referenced in `metadata_list` does not exist in this knowledge base." } }, "summary": "Update Document Metadata in Batch", "tags": [ "Metadata" ], "x-mint": { "href": "/en/api-reference/metadata/update-document-metadata-in-batch", "metadata": { "sidebarTitle": "Update Document Metadata in Batch", "title": "Update Document Metadata in Batch" } } } }, "/datasets/{dataset_id}/documents/status/{action}": { "patch": { "description": "Enables, disables, archives, or unarchives multiple documents in one request.", "operationId": "batchUpdateDocumentStatus", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "`enable` activates documents for retrieval, `disable` deactivates them, `archive` moves them to the archive, `un_archive` restores them from the archive.", "in": "path", "name": "action", "required": true, "schema": { "enum": [ "enable", "disable", "archive", "un_archive" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "document_ids": { "description": "Document IDs to update. Get them from [List Documents](/en/api-reference/documents/list-documents).", "items": { "type": "string" }, "type": "array" } }, "required": [ "document_ids" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "result": "success" } } }, "schema": { "properties": { "result": { "description": "Operation result.", "type": "string" } }, "type": "object" } } }, "description": "Documents updated successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_action": { "summary": "invalid_action", "value": { "code": "invalid_action", "message": "Invalid action.", "status": 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)." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Knowledge base not found." } }, "summary": "Update Document Status in Batch", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/update-document-status-in-batch", "metadata": { "sidebarTitle": "Update Document Status in Batch", "title": "Update Document Status in Batch" } } } }, "/datasets/{dataset_id}/documents/{batch}/indexing-status": { "get": { "description": "Returns indexing progress for every document in a batch: the current stage and chunk completion counts. Poll until each `indexing_status` reaches `completed` or `error`. Status advances through `waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`.", "operationId": "getDocumentIndexingStatus", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Batch ID returned when you create or update a document.", "in": "path", "name": "batch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "cleaning_completed_at": 1741267200, "completed_at": 1741267200, "completed_segments": 5, "error": null, "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_status": "completed", "parsing_completed_at": 1741267200, "paused_at": null, "processing_started_at": 1741267200, "splitting_completed_at": 1741267200, "stopped_at": null, "total_segments": 5 } ] } } }, "schema": { "properties": { "data": { "description": "List of indexing status entries.", "items": { "properties": { "cleaning_completed_at": { "description": "Unix timestamp when cleaning completed.", "nullable": true, "type": "number" }, "completed_at": { "description": "Unix timestamp when indexing completed.", "nullable": true, "type": "number" }, "completed_segments": { "description": "Number of chunks that have been indexed.", "type": "integer" }, "error": { "description": "Error message if indexing failed. `null` if no error.", "nullable": true, "type": "string" }, "id": { "description": "Document identifier.", "type": "string" }, "indexing_status": { "description": "Current indexing status: `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, or `error`.", "type": "string" }, "parsing_completed_at": { "description": "Unix timestamp when parsing completed.", "nullable": true, "type": "number" }, "paused_at": { "description": "Timestamp when indexing was paused. `null` if not paused.", "nullable": true, "type": "number" }, "processing_started_at": { "description": "Unix timestamp when processing started.", "nullable": true, "type": "number" }, "splitting_completed_at": { "description": "Unix timestamp when splitting completed.", "nullable": true, "type": "number" }, "stopped_at": { "description": "Timestamp when indexing was stopped. `null` if not stopped.", "nullable": true, "type": "number" }, "total_segments": { "description": "Total number of chunks to be indexed.", "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Indexing status for documents in the batch." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "dataset_not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "documents_not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Documents not found.", "status": 404 } } } } }, "description": "- `not_found` : Knowledge base not found.\n- `not_found` : Documents not found." } }, "summary": "Get Document Indexing Status", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/get-document-indexing-status", "metadata": { "sidebarTitle": "Get Document Indexing Status", "title": "Get Document Indexing Status" } } } }, "/datasets/{dataset_id}/documents/{document_id}": { "delete": { "description": "Permanently deletes a document and all its chunks from the knowledge base.", "operationId": "deleteDocument", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Success." }, "403": { "content": { "application/json": { "examples": { "archived_document_immutable": { "summary": "archived_document_immutable", "value": { "code": "archived_document_immutable", "message": "The archived document is not editable.", "status": 403 } }, "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `archived_document_immutable` : The archived document is not editable.\n- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Document Not Exists.", "status": 404 } }, "not_found_2": { "summary": "not_found_2", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : The document does not exist. Also returned as \"Dataset not found.\" when the knowledge base itself does not exist." } }, "summary": "Delete Document", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/delete-document", "metadata": { "sidebarTitle": "Delete Document", "title": "Delete Document" } } }, "get": { "description": "Returns detailed information for a single document.", "operationId": "getDocumentDetail", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "`all` returns all fields including metadata. `only` returns only `id`, `doc_type`, and `doc_metadata`. `without` returns all fields except `doc_type` and `doc_metadata`.", "in": "query", "name": "metadata", "schema": { "default": "all", "enum": [ "all", "only", "without" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "archived": false, "average_segment_length": 70.0, "completed_at": 1741267260, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_from": "api", "data_source_info": { "upload_file": { "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "extension": "txt", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mime_type": "text/plain", "name": "guide.txt", "size": 2048 } }, "data_source_type": "upload_file", "dataset_process_rule": { "id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "mode": "custom" }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "disabled_at": null, "disabled_by": null, "display_status": "available", "doc_form": "text_model", "doc_language": "English", "doc_metadata": [], "doc_type": null, "document_process_rule": { "mode": "custom", "rules": { "pre_processing_rules": [], "segmentation": { "chunk_overlap": 50, "max_tokens": 500, "separator": "###" } } }, "enabled": true, "error": null, "hit_count": 0, "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_latency": 60.0, "indexing_status": "completed", "name": "guide.txt", "need_summary": false, "position": 1, "segment_count": 5, "summary_index_status": null, "tokens": 512, "updated_at": 1741267260 } } }, "schema": { "properties": { "archived": { "description": "Whether the document is archived.", "type": "boolean" }, "average_segment_length": { "description": "Average character length of chunks.", "type": "number" }, "completed_at": { "description": "Unix timestamp when processing completed, `null` if not yet completed.", "nullable": true, "type": "number" }, "created_at": { "description": "Unix timestamp of document creation.", "type": "number" }, "created_by": { "description": "ID of the user who created the document.", "type": "string" }, "created_from": { "description": "Origin of the document. `api` for API creation, `web` for UI creation.", "type": "string" }, "data_source_info": { "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": { "description": "Uploaded file details. Present when `data_source_type` is `upload_file`.", "properties": { "created_at": { "description": "Unix timestamp of file upload.", "type": "integer" }, "created_by": { "description": "ID of the user who uploaded the file.", "type": "string" }, "extension": { "description": "File extension.", "type": "string" }, "id": { "description": "File identifier.", "type": "string" }, "mime_type": { "description": "File MIME type.", "type": "string" }, "name": { "description": "Original file name.", "type": "string" }, "size": { "description": "File size in bytes.", "type": "integer" } }, "type": "object" } }, "type": "object" }, "data_source_type": { "description": "How the document was uploaded. `upload_file` for file uploads, `notion_import` for Notion imports.", "type": "string" }, "dataset_process_rule": { "description": "Knowledge-base-level processing rule configuration.", "type": "object" }, "dataset_process_rule_id": { "description": "ID of the processing rule applied to this document.", "type": "string" }, "disabled_at": { "description": "Unix timestamp when the document was disabled, `null` if enabled.", "nullable": true, "type": "number" }, "disabled_by": { "description": "ID of the user who disabled the document, `null` if enabled.", "nullable": true, "type": "string" }, "display_status": { "description": "Display-friendly indexing status for the UI.", "type": "string" }, "doc_form": { "description": "Document chunking mode. `text_model` for standard text, `hierarchical_model` for parent-child, `qa_model` for QA pairs.", "type": "string" }, "doc_language": { "description": "Language of the document content.", "type": "string" }, "doc_metadata": { "description": "Custom metadata key-value pairs for this document.", "items": { "properties": { "id": { "description": "Metadata field identifier.", "type": "string" }, "name": { "description": "Metadata field name.", "type": "string" }, "type": { "description": "Metadata field type.", "type": "string" }, "value": { "description": "Metadata field value for this document.", "type": "string" } }, "type": "object" }, "type": "array" }, "doc_type": { "description": "Document type classification, `null` if not set.", "nullable": true, "type": "string" }, "document_process_rule": { "description": "Document-level processing rule configuration.", "type": "object" }, "enabled": { "description": "Whether the document is enabled for retrieval.", "type": "boolean" }, "error": { "description": "Error message if indexing failed, `null` otherwise.", "nullable": true, "type": "string" }, "hit_count": { "description": "Number of times this document has been retrieved.", "type": "integer" }, "id": { "description": "Document identifier.", "type": "string" }, "indexing_latency": { "description": "Time taken for indexing in seconds, `null` if not completed.", "nullable": true, "type": "number" }, "indexing_status": { "description": "Current indexing status, e.g. `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, `error`, `paused`.", "type": "string" }, "name": { "description": "Document name.", "type": "string" }, "need_summary": { "description": "Whether the document needs summary generation.", "type": "boolean" }, "position": { "description": "Position index within the knowledge base.", "type": "integer" }, "segment_count": { "description": "Number of chunks in the document.", "type": "integer" }, "summary_index_status": { "description": "Status of summary indexing, `null` if summary index is not enabled.", "nullable": true, "type": "string" }, "tokens": { "description": "Number of tokens in the document.", "type": "integer" }, "updated_at": { "description": "Unix timestamp of last update, `null` if never updated.", "nullable": true, "type": "number" } }, "type": "object" } } }, "description": "Document details. The returned fields depend on the `metadata` query parameter." }, "400": { "content": { "application/json": { "examples": { "invalid_metadata": { "summary": "invalid_metadata", "value": { "code": "invalid_metadata", "message": "Invalid metadata value: full", "status": 400 } } } } }, "description": "`invalid_metadata` : The `metadata` query parameter value is invalid (must be `all`, `only`, or `without`)." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (no permission)", "value": { "code": "forbidden", "message": "No permission.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : You do not have permission to access this document.\n- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_2": { "summary": "not_found_2", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Document not found. Also returned as \"Dataset not found.\" when the knowledge base itself does not exist." } }, "summary": "Get Document", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/get-document", "metadata": { "sidebarTitle": "Get Document", "title": "Get Document" } } }, "patch": { "description": "Updates a document by uploading a new file, then re-indexes it. This is the canonical endpoint for file-based document updates. Track progress with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).", "operationId": "updateDocument", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "data": { "description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.", "example": "{\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}", "type": "string" }, "file": { "description": "File to upload, capped at 15 MB by default.\n\nSelf-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments). On Dify Cloud, Professional and Team plans raise the cap to 50 MB.", "format": "binary", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "batch": "20250306150245647595", "document": { "archived": false, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_from": "api", "data_source_detail_dict": { "upload_file": { "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "extension": "txt", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mime_type": "text/plain", "name": "guide.txt", "size": 2048 } }, "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_type": "upload_file", "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "disabled_at": null, "disabled_by": null, "display_status": "available", "doc_form": "text_model", "doc_metadata": [], "enabled": true, "error": null, "hit_count": 0, "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_status": "completed", "name": "guide.txt", "need_summary": false, "position": 1, "summary_index_status": null, "tokens": 512, "word_count": 350 } } } }, "schema": { "properties": { "batch": { "description": "Batch ID for tracking indexing progress.", "type": "string" }, "document": { "$ref": "#/components/schemas/Document" } }, "type": "object" } } }, "description": "Document updated successfully." }, "400": { "content": { "application/json": { "examples": { "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "code": "filename_not_exists_error", "message": "The specified filename does not exist.", "status": 400 } }, "invalid_param_not_available": { "summary": "invalid_param (not available)", "value": { "code": "invalid_param", "message": "Document is not available", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "too_many_files": { "summary": "too_many_files", "value": { "code": "too_many_files", "message": "Only one file is allowed.", "status": 400 } } } } }, "description": "- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : The document is not available for update (only available documents can be updated)." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } } } } }, "description": "- `not_found` : Knowledge base not found.\n- `not_found` : Document not found." }, "413": { "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "code": "file_too_large", "message": "File size exceeded.", "status": 413 } } } } }, "description": "`file_too_large` : The uploaded file exceeds the maximum size." }, "415": { "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "code": "unsupported_file_type", "message": "File type not allowed.", "status": 415 } } } } }, "description": "`unsupported_file_type` : The uploaded file's type is not supported." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later.", "status": 503 } } } } }, "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later." } }, "summary": "Update Document", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/update-document", "metadata": { "sidebarTitle": "Update Document", "title": "Update Document" } } } }, "/datasets/{dataset_id}/documents/{document_id}/download": { "get": { "description": "Returns a signed URL for downloading a document's original uploaded file.", "operationId": "downloadDocument", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600" } } }, "schema": { "properties": { "url": { "description": "Signed URL to download the original uploaded file.", "type": "string" } }, "type": "object" } } }, "description": "Download URL generated successfully." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (no permission)", "value": { "code": "forbidden", "message": "No permission.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : You do not have permission to access this document.\n- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_2": { "summary": "not_found_2", "value": { "code": "not_found", "message": "Uploaded file not found.", "status": 404 } }, "not_found_3": { "summary": "not_found_3", "value": { "code": "not_found", "message": "Document does not have an uploaded file to download.", "status": 404 } } } } }, "description": "`not_found` : Document not found. Also returned as \"Uploaded file not found.\" when the stored file is missing, and \"Document does not have an uploaded file to download.\" for non-file documents." } }, "summary": "Download Document", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/download-document", "metadata": { "sidebarTitle": "Download Document", "title": "Download Document" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments": { "get": { "description": "Returns a paginated list of chunks within a document, optionally filtered by keyword or indexing status.", "operationId": "listSegments", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Number of items per page. Server caps at `100`.", "in": "query", "name": "limit", "schema": { "default": 20, "minimum": 1, "type": "integer" } }, { "description": "Filter chunks by indexing status, e.g. `completed`, `indexing`, `error`.", "explode": true, "in": "query", "name": "status", "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" }, { "description": "Search keyword.", "in": "query", "name": "keyword", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "answer": "", "attachments": [], "child_chunks": [], "completed_at": 1741267200, "content": "Dify is an open-source LLM app development platform.", "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "disabled_at": null, "disabled_by": null, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "enabled": true, "error": null, "hit_count": 0, "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "index_node_hash": "abc123def456", "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "indexing_at": 1741267200, "keywords": [ "dify", "platform", "llm" ], "position": 1, "sign_content": "", "status": "completed", "stopped_at": null, "summary": null, "tokens": 12, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "word_count": 9 } ], "doc_form": "text_model", "has_more": false, "limit": 20, "page": 1, "total": 1 } } }, "schema": { "properties": { "data": { "description": "List of chunks.", "items": { "$ref": "#/components/schemas/Segment" }, "type": "array" }, "doc_form": { "description": "Document chunking mode used by this document.", "type": "string" }, "has_more": { "description": "Whether more items exist on the next page.", "type": "boolean" }, "limit": { "description": "Number of items per page.", "type": "integer" }, "page": { "description": "Current page number.", "type": "integer" }, "total": { "description": "Total number of matching chunks.", "type": "integer" } }, "type": "object" } } }, "description": "List of chunks." }, "400": { "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.", "status": 400 } } } } }, "description": "`provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } } } } }, "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found." } }, "summary": "List Chunks", "tags": [ "Chunks" ], "x-mint": { "href": "/en/api-reference/chunks/list-chunks", "metadata": { "sidebarTitle": "List Chunks", "title": "List Chunks" } } }, "post": { "description": "Create one or more chunks within a document.", "operationId": "createSegments", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "segments": { "description": "Array of chunk objects to create.", "items": { "properties": { "answer": { "description": "Answer text. Required for Q&A-mode (`qa_model`) documents.", "type": "string" }, "attachment_ids": { "description": "Attachment file IDs.", "items": { "type": "string" }, "type": "array" }, "content": { "description": "Chunk text content.", "minLength": 1, "type": "string" }, "keywords": { "description": "Keywords for the chunk.", "items": { "type": "string" }, "type": "array" } }, "required": [ "content" ], "type": "object" }, "minItems": 1, "type": "array" } }, "required": [ "segments" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "answer": "", "attachments": [], "child_chunks": [], "completed_at": 1741267200, "content": "Dify is an open-source LLM app development platform.", "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "disabled_at": null, "disabled_by": null, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "enabled": true, "error": null, "hit_count": 0, "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "index_node_hash": "abc123def456", "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "indexing_at": 1741267200, "keywords": [ "dify", "platform", "llm" ], "position": 1, "sign_content": "", "status": "completed", "stopped_at": null, "summary": null, "tokens": 12, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "word_count": 9 } ], "doc_form": "text_model" } } }, "schema": { "properties": { "data": { "description": "List of created chunks.", "items": { "$ref": "#/components/schemas/Segment" }, "type": "array" }, "doc_form": { "description": "Document chunking mode used by this document.", "type": "string" } }, "type": "object" } } }, "description": "Chunks created successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param_limit": { "summary": "invalid_param (segments limit)", "value": { "code": "invalid_param", "message": "Exceeded maximum segments limit of 1000.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.", "status": 400 } }, "validation_error": { "summary": "schema validation (non-standard body)", "value": { "error": "1 validation error for SegmentCreatePayload\nsegments.0.content\n String should have at least 1 character [type=string_too_short, input_value='', input_type=str]" } } } } }, "description": "- `provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : A chunk field is invalid (for example, `answer` is required for Q&A-mode documents) or the number of chunks exceeds the per-request limit.\n- Request-body schema validation (such as empty `content`) returns a non-standard body `{\"error\": \"\"}` with no `code` or `status` field." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (upgrade plan)", "value": { "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "status": 403 } }, "forbidden_5": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_3": { "summary": "not_found", "value": { "code": "not_found", "message": "Document is not completed.", "status": 404 } }, "not_found_4": { "summary": "not_found", "value": { "code": "not_found", "message": "Document is disabled.", "status": 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." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later.", "status": 503 } } } } }, "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later." } }, "summary": "Create Chunks", "tags": [ "Chunks" ], "x-mint": { "href": "/en/api-reference/chunks/create-chunks", "metadata": { "sidebarTitle": "Create Chunks", "title": "Create Chunks" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { "delete": { "description": "Permanently delete a chunk from the document.", "operationId": "deleteSegment", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).", "in": "path", "name": "segment_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Success." }, "400": { "content": { "application/json": { "examples": { "invalid_param_deleting": { "summary": "invalid_param (deleting)", "value": { "code": "invalid_param", "message": "Segment is deleting.", "status": 400 } }, "invalid_param_model_setting": { "summary": "invalid_param (model setting)", "value": { "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.", "status": 400 } } } } }, "description": "- `invalid_param` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : The chunk is already being deleted by a concurrent request." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_3": { "summary": "not_found", "value": { "code": "not_found", "message": "Segment not found.", "status": 404 } } } } }, "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found." } }, "summary": "Delete Chunk", "tags": [ "Chunks" ], "x-mint": { "href": "/en/api-reference/chunks/delete-chunk", "metadata": { "sidebarTitle": "Delete Chunk", "title": "Delete Chunk" } } }, "get": { "description": "Retrieve the full details of a single chunk.", "operationId": "getSegmentDetail", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).", "in": "path", "name": "segment_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": { "answer": "", "attachments": [], "child_chunks": [], "completed_at": 1741267200, "content": "Dify is an open-source LLM app development platform.", "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "disabled_at": null, "disabled_by": null, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "enabled": true, "error": null, "hit_count": 0, "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "index_node_hash": "abc123def456", "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "indexing_at": 1741267200, "keywords": [ "dify", "platform", "llm" ], "position": 1, "sign_content": "", "status": "completed", "stopped_at": null, "summary": null, "tokens": 12, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "word_count": 9 }, "doc_form": "text_model" } } }, "schema": { "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "doc_form": { "description": "Document chunking mode used by this document.", "type": "string" } }, "type": "object" } } }, "description": "Chunk details." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.", "status": 400 } } } } }, "description": "`invalid_param` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_3": { "summary": "not_found", "value": { "code": "not_found", "message": "Segment not found.", "status": 404 } } } } }, "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found." } }, "summary": "Get Chunk", "tags": [ "Chunks" ], "x-mint": { "href": "/en/api-reference/chunks/get-chunk", "metadata": { "sidebarTitle": "Get Chunk", "title": "Get Chunk" } } }, "post": { "description": "Update a chunk's fields. The update re-triggers indexing for that chunk.", "operationId": "updateSegment", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).", "in": "path", "name": "segment_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "segment": { "description": "Chunk data to update.", "properties": { "answer": { "description": "Answer text for Q&A-mode (`qa_model`) documents.", "type": "string" }, "attachment_ids": { "description": "Attachment file IDs.", "items": { "type": "string" }, "type": "array" }, "content": { "description": "Chunk text content.", "type": "string" }, "enabled": { "description": "Whether the chunk is enabled.", "type": "boolean" }, "keywords": { "description": "Keywords for the chunk.", "items": { "type": "string" }, "type": "array" }, "regenerate_child_chunks": { "default": false, "description": "Whether to regenerate child chunks.", "type": "boolean" }, "summary": { "description": "Summary content for summary index.", "nullable": true, "type": "string" } }, "type": "object" } }, "required": [ "segment" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": { "answer": "", "attachments": [], "child_chunks": [], "completed_at": 1741267200, "content": "Dify is an open-source LLM app development platform.", "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "disabled_at": null, "disabled_by": null, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "enabled": true, "error": null, "hit_count": 0, "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "index_node_hash": "abc123def456", "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "indexing_at": 1741267200, "keywords": [ "dify", "platform", "llm" ], "position": 1, "sign_content": "", "status": "completed", "stopped_at": null, "summary": null, "tokens": 12, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "word_count": 9 }, "doc_form": "text_model" } } }, "schema": { "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "doc_form": { "description": "Document chunking mode used by this document.", "type": "string" } }, "type": "object" } } }, "description": "Chunk updated successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param_state": { "summary": "invalid_param (state)", "value": { "code": "invalid_param", "message": "Segment is indexing, please try again later", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.", "status": 400 } } } } }, "description": "- `provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : The chunk is indexing or disabled and cannot be updated, or index configuration is invalid." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_3": { "summary": "not_found", "value": { "code": "not_found", "message": "Segment not found.", "status": 404 } } } } }, "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later.", "status": 503 } } } } }, "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later." } }, "summary": "Update Chunk", "tags": [ "Chunks" ], "x-mint": { "href": "/en/api-reference/chunks/update-chunk", "metadata": { "sidebarTitle": "Update Chunk", "title": "Update Chunk" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { "get": { "description": "Returns a paginated list of child chunks under a specific parent chunk.", "operationId": "getChildChunks", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).", "in": "path", "name": "segment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Number of items per page. Server caps at `100`.", "in": "query", "name": "limit", "schema": { "default": 20, "minimum": 1, "type": "integer" } }, { "description": "Search keyword.", "in": "query", "name": "keyword", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "content": "Dify is an open-source platform.", "created_at": 1741267200, "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "position": 1, "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "type": "customized", "updated_at": 1741267200, "word_count": 6 } ], "limit": 20, "page": 1, "total": 1, "total_pages": 1 } } }, "schema": { "properties": { "data": { "description": "List of child chunks.", "items": { "$ref": "#/components/schemas/ChildChunk" }, "type": "array" }, "limit": { "description": "Number of items per page.", "type": "integer" }, "page": { "description": "Current page number.", "type": "integer" }, "total": { "description": "Total number of child chunks.", "type": "integer" }, "total_pages": { "description": "Total number of pages.", "type": "integer" } }, "type": "object" } } }, "description": "List of child chunks." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_3": { "summary": "not_found", "value": { "code": "not_found", "message": "Segment not found.", "status": 404 } } } } }, "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found." } }, "summary": "List Child Chunks", "tags": [ "Chunks" ], "x-mint": { "href": "/en/api-reference/chunks/list-child-chunks", "metadata": { "sidebarTitle": "List Child Chunks", "title": "List Child Chunks" } } }, "post": { "description": "Create a child chunk under a parent chunk. Intended for documents that use the parent-child (`hierarchical_model`) chunking mode.", "operationId": "createChildChunk", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).", "in": "path", "name": "segment_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content": { "description": "Child chunk text content.", "type": "string" } }, "required": [ "content" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": { "content": "Dify is an open-source platform.", "created_at": 1741267200, "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "position": 1, "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "type": "customized", "updated_at": 1741267200, "word_count": 6 } } } }, "schema": { "properties": { "data": { "$ref": "#/components/schemas/ChildChunk" } }, "type": "object" } } }, "description": "Child chunk created successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Vector store operation failed: [Errno 111] Connection refused", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.", "status": 400 } } } } }, "description": "- `provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : Indexing the child chunk in the vector store failed; the message carries the underlying vector-store error." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (upgrade plan)", "value": { "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "status": 403 } }, "forbidden_5": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_3": { "summary": "not_found", "value": { "code": "not_found", "message": "Segment not found.", "status": 404 } } } } }, "description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later.", "status": 503 } } } } }, "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later." } }, "summary": "Create Child Chunk", "tags": [ "Chunks" ], "x-mint": { "href": "/en/api-reference/chunks/create-child-chunk", "metadata": { "sidebarTitle": "Create Child Chunk", "title": "Create Child Chunk" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { "delete": { "description": "Permanently delete a child chunk from its parent chunk.", "operationId": "deleteChildChunk", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).", "in": "path", "name": "segment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Child chunk ID.", "in": "path", "name": "child_chunk_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Success." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Vector store operation failed: [Errno 111] Connection refused", "status": 400 } } } } }, "description": "`invalid_param` : Removing the child chunk index from the vector store failed; the message carries the underlying vector-store error." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (upgrade plan)", "value": { "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_3": { "summary": "not_found", "value": { "code": "not_found", "message": "Segment not found.", "status": 404 } }, "not_found_4": { "summary": "not_found", "value": { "code": "not_found", "message": "Child chunk not found.", "status": 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." } }, "summary": "Delete Child Chunk", "tags": [ "Chunks" ], "x-mint": { "href": "/en/api-reference/chunks/delete-child-chunk", "metadata": { "sidebarTitle": "Delete Child Chunk", "title": "Delete Child Chunk" } } }, "patch": { "description": "Update the content of an existing child chunk.", "operationId": "updateChildChunk", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).", "in": "path", "name": "segment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Child chunk ID.", "in": "path", "name": "child_chunk_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content": { "description": "Child chunk text content.", "type": "string" } }, "required": [ "content" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": { "content": "Dify is an open-source platform.", "created_at": 1741267200, "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "position": 1, "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "type": "customized", "updated_at": 1741267200, "word_count": 6 } } } }, "schema": { "properties": { "data": { "$ref": "#/components/schemas/ChildChunk" } }, "type": "object" } } }, "description": "Child chunk updated successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Vector store operation failed: [Errno 111] Connection refused", "status": 400 } } } } }, "description": "`invalid_param` : Re-indexing the child chunk in the vector store failed; the message carries the underlying vector-store error." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (upgrade plan)", "value": { "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "status": 403 } }, "forbidden_5": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } }, "not_found_3": { "summary": "not_found", "value": { "code": "not_found", "message": "Segment not found.", "status": 404 } }, "not_found_4": { "summary": "not_found", "value": { "code": "not_found", "message": "Child chunk not found.", "status": 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." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later.", "status": 503 } } } } }, "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later." } }, "summary": "Update Child Chunk", "tags": [ "Chunks" ], "x-mint": { "href": "/en/api-reference/chunks/update-child-chunk", "metadata": { "sidebarTitle": "Update Child Chunk", "title": "Update Child Chunk" } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { "post": { "deprecated": true, "description": "Deprecated. Use [Update Document](/en/api-reference/documents/update-document) instead. Updates a document by uploading a new file, then re-indexes it.", "operationId": "updateDocumentByFile", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "data": { "description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.", "example": "{\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}", "type": "string" }, "file": { "description": "File to upload, capped at 15 MB by default.\n\nSelf-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments). On Dify Cloud, Professional and Team plans raise the cap to 50 MB.", "format": "binary", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "batch": "20250306150245647595", "document": { "archived": false, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_from": "api", "data_source_detail_dict": { "upload_file": { "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "extension": "txt", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mime_type": "text/plain", "name": "guide.txt", "size": 2048 } }, "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_type": "upload_file", "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "disabled_at": null, "disabled_by": null, "display_status": "available", "doc_form": "text_model", "doc_metadata": [], "enabled": true, "error": null, "hit_count": 0, "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_status": "completed", "name": "guide.txt", "need_summary": false, "position": 1, "summary_index_status": null, "tokens": 512, "word_count": 350 } } } }, "schema": { "properties": { "batch": { "description": "Batch ID for tracking indexing progress.", "type": "string" }, "document": { "$ref": "#/components/schemas/Document" } }, "type": "object" } } }, "description": "Document updated successfully." }, "400": { "content": { "application/json": { "examples": { "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "code": "filename_not_exists_error", "message": "The specified filename does not exist.", "status": 400 } }, "invalid_param_not_available": { "summary": "invalid_param (not available)", "value": { "code": "invalid_param", "message": "Document is not available", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "too_many_files": { "summary": "too_many_files", "value": { "code": "too_many_files", "message": "Only one file is allowed.", "status": 400 } } } } }, "description": "- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : The document is not available for update (only available documents can be updated)." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } } } } }, "description": "- `not_found` : Knowledge base not found.\n- `not_found` : Document not found." }, "413": { "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "code": "file_too_large", "message": "File size exceeded.", "status": 413 } } } } }, "description": "`file_too_large` : The uploaded file exceeds the maximum size." }, "415": { "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "code": "unsupported_file_type", "message": "File type not allowed.", "status": 415 } } } } }, "description": "`unsupported_file_type` : The uploaded file's type is not supported." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later.", "status": 503 } } } } }, "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later." } }, "summary": "Update Document by File", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/update-document-by-file", "metadata": { "sidebarTitle": "Update Document by File", "title": "Update Document by File" } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { "post": { "description": "Updates a document's text content, name, or processing configuration. Re-indexes the document when its text changes.", "operationId": "updateDocumentByText", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents).", "in": "path", "name": "document_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "doc_form": { "default": "text_model", "description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction.", "enum": [ "text_model", "hierarchical_model", "qa_model" ], "type": "string" }, "doc_language": { "default": "English", "description": "Language of the document for processing optimization.", "type": "string" }, "name": { "description": "Document name. Required when `text` is provided.", "type": "string" }, "process_rule": { "description": "Processing rules for chunking.", "properties": { "mode": { "description": "`automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`).", "enum": [ "automatic", "custom", "hierarchical" ], "type": "string" }, "rules": { "properties": { "pre_processing_rules": { "items": { "properties": { "enabled": { "description": "Whether this preprocessing rule is enabled.", "type": "boolean" }, "id": { "description": "Rule identifier.", "enum": [ "remove_stopwords", "remove_extra_spaces", "remove_urls_emails" ], "type": "string" } }, "type": "object" }, "type": "array" }, "segmentation": { "properties": { "chunk_overlap": { "default": 0, "description": "Token overlap between chunks.", "type": "integer" }, "max_tokens": { "description": "Maximum token count per chunk.", "type": "integer" }, "separator": { "default": "\n", "description": "Custom separator for splitting text.", "type": "string" } }, "type": "object" } }, "type": "object" } }, "required": [ "mode" ], "type": "object" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Controls how chunks are searched and ranked when querying this knowledge base." }, "text": { "description": "Document text content.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "batch": "20250306150245647595", "document": { "archived": false, "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_from": "api", "data_source_detail_dict": { "upload_file": { "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "extension": "txt", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mime_type": "text/plain", "name": "guide.txt", "size": 2048 } }, "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_type": "upload_file", "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "disabled_at": null, "disabled_by": null, "display_status": "available", "doc_form": "text_model", "doc_metadata": [], "enabled": true, "error": null, "hit_count": 0, "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_status": "completed", "name": "guide.txt", "need_summary": false, "position": 1, "summary_index_status": null, "tokens": 512, "word_count": 350 } } } }, "schema": { "properties": { "batch": { "description": "Batch ID for tracking indexing progress.", "type": "string" }, "document": { "$ref": "#/components/schemas/Document" } }, "type": "object" } } }, "description": "Document updated successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param_name": { "summary": "invalid_param (name required)", "value": { "code": "invalid_param", "message": "name is required when text is provided.", "status": 400 } }, "invalid_param_not_available": { "summary": "invalid_param (not available)", "value": { "code": "invalid_param", "message": "Document is not available", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } } } } }, "description": "- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : `name` is required when `text` is provided, or `doc_form` is invalid.\n- `invalid_param` : The document is not available for update (only available documents can be updated)." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_4": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } }, "not_found_2": { "summary": "not_found", "value": { "code": "not_found", "message": "Document not found.", "status": 404 } } } } }, "description": "- `not_found` : Knowledge base not found.\n- `not_found` : Document not found." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "code": "service_unavailable", "message": "Unable to verify vector space usage right now. Please try again later.", "status": 503 } } } } }, "description": "`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later." } }, "summary": "Update Document by Text", "tags": [ "Documents" ], "x-mint": { "href": "/en/api-reference/documents/update-document-by-text", "metadata": { "sidebarTitle": "Update Document by Text", "title": "Update Document by Text" } } } }, "/datasets/{dataset_id}/metadata": { "get": { "description": "Returns all metadata fields for the knowledge base, both custom and built-in, with the count of documents using each field.", "operationId": "listMetadataFields", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "built_in_field_enabled": true, "doc_metadata": [ { "count": 3, "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", "name": "author", "type": "string" } ] } } }, "schema": { "properties": { "built_in_field_enabled": { "description": "Whether built-in metadata fields are enabled for this knowledge base.", "type": "boolean" }, "doc_metadata": { "description": "List of metadata field definitions.", "items": { "properties": { "count": { "description": "Number of documents using this metadata field.", "type": "integer" }, "id": { "description": "Metadata field identifier.", "type": "string" }, "name": { "description": "Metadata field name.", "type": "string" }, "type": { "description": "Metadata field type.", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Metadata fields for the knowledge base." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Dataset not found." } }, "summary": "List Metadata Fields", "tags": [ "Metadata" ], "x-mint": { "href": "/en/api-reference/metadata/list-metadata-fields", "metadata": { "sidebarTitle": "List Metadata Fields", "title": "List Metadata Fields" } } }, "post": { "description": "Create a custom metadata field for annotating documents in the knowledge base with structured information.", "operationId": "createMetadataField", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Name for the metadata field. Must be unique among the knowledge base's fields and at most 255 characters.", "type": "string" }, "type": { "description": "`string` for text values, `number` for numeric values, `time` for date/time values.", "enum": [ "string", "number", "time" ], "type": "string" } }, "required": [ "type", "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", "name": "author", "type": "string" } } }, "schema": { "properties": { "id": { "description": "Metadata field identifier.", "type": "string" }, "name": { "description": "Metadata field name.", "type": "string" }, "type": { "description": "Metadata field type.", "type": "string" } }, "type": "object" } } }, "description": "Metadata field created successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Metadata name already exists.", "status": 400 } } } } }, "description": "`invalid_param` : The metadata name already exists, exceeds 255 characters, or conflicts with a built-in field." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Dataset not found." } }, "summary": "Create Metadata Field", "tags": [ "Metadata" ], "x-mint": { "href": "/en/api-reference/metadata/create-metadata-field", "metadata": { "sidebarTitle": "Create Metadata Field", "title": "Create Metadata Field" } } } }, "/datasets/{dataset_id}/metadata/built-in": { "get": { "description": "Returns the built-in metadata fields provided by the system.", "operationId": "getBuiltInMetadataFields", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "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" } ] } } }, "schema": { "properties": { "fields": { "description": "List of system-provided metadata fields.", "items": { "properties": { "name": { "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": "string" }, "type": { "description": "Field data type. `string` for text values, `time` for date/time values.", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Built-in metadata fields." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Dataset not found." } }, "summary": "Get Built-in Metadata Fields", "tags": [ "Metadata" ], "x-mint": { "href": "/en/api-reference/metadata/get-built-in-metadata-fields", "metadata": { "sidebarTitle": "Get Built-in Metadata Fields", "title": "Get Built-in Metadata Fields" } } } }, "/datasets/{dataset_id}/metadata/built-in/{action}": { "post": { "description": "Enable or disable built-in metadata fields for the knowledge base.", "operationId": "toggleBuiltInMetadataField", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "`enable` to activate built-in metadata fields, `disable` to deactivate them.", "in": "path", "name": "action", "required": true, "schema": { "enum": [ "enable", "disable" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "result": "success" } } }, "schema": { "properties": { "result": { "description": "Operation result.", "type": "string" } }, "type": "object" } } }, "description": "Built-in metadata field toggled successfully." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Dataset not found." } }, "summary": "Update Built-in Metadata Field", "tags": [ "Metadata" ], "x-mint": { "href": "/en/api-reference/metadata/update-built-in-metadata-field", "metadata": { "sidebarTitle": "Update Built-in Metadata Field", "title": "Update Built-in Metadata Field" } } } }, "/datasets/{dataset_id}/metadata/{metadata_id}": { "delete": { "description": "Permanently delete a custom metadata field. Documents that used the field lose their values for it.", "operationId": "deleteMetadataField", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "ID of the metadata field to delete. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields).", "in": "path", "name": "metadata_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Success." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Dataset not found." } }, "summary": "Delete Metadata Field", "tags": [ "Metadata" ], "x-mint": { "href": "/en/api-reference/metadata/delete-metadata-field", "metadata": { "sidebarTitle": "Delete Metadata Field", "title": "Delete Metadata Field" } } }, "patch": { "description": "Rename a custom metadata field.", "operationId": "updateMetadataField", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "ID of the metadata field to rename. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields).", "in": "path", "name": "metadata_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "New name for the field. Must be unique among the knowledge base's fields and at most 255 characters.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", "name": "author", "type": "string" } } }, "schema": { "properties": { "id": { "description": "Metadata field identifier.", "type": "string" }, "name": { "description": "Metadata field name.", "type": "string" }, "type": { "description": "Metadata field type.", "type": "string" } }, "type": "object" } } }, "description": "Metadata field updated successfully." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Metadata name already exists.", "status": 400 } } } } }, "description": "`invalid_param` : The metadata name already exists, exceeds 255 characters, or conflicts with a built-in field." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 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` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Dataset not found." } }, "summary": "Update Metadata Field", "tags": [ "Metadata" ], "x-mint": { "href": "/en/api-reference/metadata/update-metadata-field", "metadata": { "sidebarTitle": "Update Metadata Field", "title": "Update Metadata Field" } } } }, "/datasets/{dataset_id}/pipeline/datasource-plugins": { "get": { "description": "Returns the datasource nodes configured in the knowledge pipeline, each with the plugin it uses and the metadata needed to run it.", "operationId": "listDatasourcePlugins", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Whether to read nodes from the published pipeline version rather than the draft.", "in": "query", "name": "is_published", "schema": { "default": true, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": [ { "credentials": [ { "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "is_default": true, "name": "Production Notion", "type": "api-key" } ], "datasource_type": "online_document", "node_id": "1719288585006", "plugin_id": "langgenius/notion_datasource", "provider_name": "notion", "title": "Notion Documents", "user_input_variables": [] } ] } }, "schema": { "items": { "properties": { "credentials": { "description": "Credentials available for authenticating with this datasource.", "items": { "properties": { "id": { "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).", "type": "string" }, "is_default": { "description": "Whether this credential is the default for the provider.", "type": "boolean" }, "name": { "description": "Display name of the credential.", "type": "string" }, "type": { "description": "Credential type defined by the datasource plugin.", "type": "string" } }, "type": "object" }, "type": "array" }, "datasource_type": { "description": "Type of datasource. One of `local_file`, `online_document`, `online_drive`, `website_crawl`.", "type": "string" }, "node_id": { "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).", "type": "string" }, "plugin_id": { "description": "ID of the datasource plugin providing this node.", "type": "string" }, "provider_name": { "description": "Provider name registered by the datasource plugin.", "type": "string" }, "title": { "description": "Display title configured for the node.", "type": "string" }, "user_input_variables": { "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": { "additionalProperties": true, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } } }, "description": "List of datasource nodes configured in the pipeline." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Pipeline not found", "status": 400 } } } } }, "description": "`invalid_param` : The knowledge base has no processing pipeline configured." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : No knowledge base matches `dataset_id`." } }, "summary": "List Datasource Plugins", "tags": [ "Knowledge Pipeline" ], "x-mint": { "href": "/en/api-reference/knowledge-pipeline/list-datasource-plugins", "metadata": { "sidebarTitle": "List Datasource Plugins", "title": "List Datasource Plugins" } } } }, "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": { "post": { "description": "Runs a single datasource node in the knowledge pipeline and streams its execution events.", "operationId": "runDatasourceNode", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "ID of the datasource node to run, from [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins).", "in": "path", "name": "node_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "credential_id": { "description": "ID of the credential to authenticate with the datasource, from the `credentials` array of [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins).", "nullable": true, "type": "string" }, "datasource_type": { "description": "Type of the datasource.", "enum": [ "online_document", "local_file", "website_crawl", "online_drive" ], "type": "string" }, "inputs": { "additionalProperties": true, "description": "Input variables for the datasource node.", "type": "object" }, "is_published": { "description": "Whether to run the published version of the node instead of the draft.", "type": "boolean" } }, "required": [ "inputs", "datasource_type", "is_published" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "Server-Sent Events stream of node execution progress and results. See [SSE Streaming](/en/api-reference/guides/streaming) for parsing.", "type": "string" } } }, "description": "Streaming response with node execution events." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Pipeline not found", "status": 400 } } } } }, "description": "`invalid_param` : The knowledge base has no processing pipeline configured, or the request body failed validation." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : No knowledge base matches `dataset_id`." } }, "summary": "Run Datasource Node", "tags": [ "Knowledge Pipeline" ], "x-mint": { "href": "/en/api-reference/knowledge-pipeline/run-datasource-node", "metadata": { "sidebarTitle": "Run Datasource Node", "title": "Run Datasource Node" } } } }, "/datasets/{dataset_id}/pipeline/run": { "post": { "description": "Runs the full knowledge pipeline over one or more datasources. `response_mode` selects a streaming or blocking response.", "operationId": "runPipeline", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "local_file": { "summary": "Request Example - Local file", "value": { "datasource_info_list": [ { "name": "quarterly-report.pdf", "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ], "datasource_type": "local_file", "inputs": {}, "is_published": true, "response_mode": "blocking", "start_node_id": "1719288585006" } }, "online_document": { "summary": "Request Example - Online document", "value": { "datasource_info_list": [ { "credential_id": "cred-789xyz", "page": { "page_id": "pg-def456", "page_name": "Product Roadmap", "type": "page" }, "workspace_id": "ws-abc123" } ], "datasource_type": "online_document", "inputs": {}, "is_published": true, "response_mode": "streaming", "start_node_id": "1719288585006" } }, "online_drive": { "summary": "Request Example - Online drive", "value": { "datasource_info_list": [ { "bucket": "my-bucket", "id": "file-abc123", "name": "meeting-notes.docx", "type": "file" } ], "datasource_type": "online_drive", "inputs": {}, "is_published": true, "response_mode": "blocking", "start_node_id": "1719288585006" } }, "website_crawl": { "summary": "Request Example - Website crawl", "value": { "datasource_info_list": [ { "title": "Getting Started Guide", "url": "https://example.com/docs/getting-started" } ], "datasource_type": "website_crawl", "inputs": {}, "is_published": true, "response_mode": "blocking", "start_node_id": "1719288585006" } } }, "schema": { "properties": { "datasource_info_list": { "description": "List of datasource objects to process. The expected item structure depends on `datasource_type`.", "items": { "oneOf": [ { "properties": { "name": { "description": "Document title. Defaults to `\"untitled\"`.", "type": "string" }, "reference": { "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.", "type": "string" } }, "required": [ "reference" ], "title": "Local File", "type": "object" }, { "properties": { "credential_id": { "description": "Credential for authenticating with the external platform. Managed via the Dify console. If omitted, the provider's default credential is used.", "type": "string" }, "page": { "description": "Page details.", "properties": { "page_id": { "description": "Page identifier.", "type": "string" }, "page_name": { "description": "Display name. Defaults to `\"untitled\"`.", "type": "string" }, "type": { "description": "Page type defined by the datasource plugin (e.g., `\"page\"`, `\"database\"`).", "type": "string" } }, "required": [ "page_id", "type" ], "type": "object" }, "workspace_id": { "description": "ID of the workspace or database in the external platform (e.g., a Notion workspace ID).", "type": "string" } }, "required": [ "workspace_id", "page" ], "title": "Online Document", "type": "object" }, { "properties": { "title": { "description": "Used as the document name. Defaults to `\"untitled\"`.", "type": "string" }, "url": { "description": "URL to crawl.", "type": "string" } }, "required": [ "url" ], "title": "Website Crawl", "type": "object" }, { "properties": { "bucket": { "description": "Storage bucket name. Required by some drive providers (e.g., S3-compatible stores); omit if the provider does not use buckets.", "type": "string" }, "id": { "description": "File or folder ID.", "type": "string" }, "name": { "description": "File name. Defaults to `\"untitled\"`.", "type": "string" }, "type": { "description": "Whether this entry is a single file or a folder to expand.", "enum": [ "file", "folder" ], "type": "string" } }, "required": [ "id", "type" ], "title": "Online Drive", "type": "object" } ] }, "type": "array" }, "datasource_type": { "description": "Type of the datasource. Determines which fields are expected in `datasource_info_list` items.", "enum": [ "local_file", "online_document", "website_crawl", "online_drive" ], "type": "string" }, "inputs": { "additionalProperties": true, "description": "Key-value pairs for pipeline input variables defined in the workflow. Pass `{}` if the pipeline has no input variables.", "type": "object" }, "is_published": { "description": "Whether to run the published version of the pipeline instead of the current draft. Run the draft to test unpublished changes.", "type": "boolean" }, "response_mode": { "description": "Response mode for the pipeline execution. `streaming` returns a Server-Sent Events stream, `blocking` waits and returns the complete result.", "enum": [ "streaming", "blocking" ], "type": "string" }, "start_node_id": { "description": "ID of the node to start execution from, from [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins).", "type": "string" } }, "required": [ "inputs", "datasource_type", "datasource_info_list", "start_node_id", "is_published", "response_mode" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Blocking Response Example", "value": { "data": { "created_at": 1741267200, "finished_at": 1741267210, "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", "outputs": {}, "status": "succeeded" }, "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321" } } }, "schema": { "additionalProperties": true, "description": "Complete pipeline execution result. Returned when `response_mode` is `blocking`.", "type": "object" } }, "text/event-stream": { "schema": { "description": "Server-Sent Events stream. Returned when `response_mode` is `streaming`; see [SSE Streaming](/en/api-reference/guides/streaming) for the wire format.\n\nKey events:\n\n- `workflow_started`: execution began\n- `node_started` / `node_finished`: per-node progress with `node_id`, `node_type`, `status`, `inputs`, `outputs`\n- `workflow_finished`: final result with `status`, `outputs`, `total_tokens`, `elapsed_time`\n- `ping`: keepalive", "type": "string" } } }, "description": "Pipeline execution result. Format depends on `response_mode`: streaming returns a `text/event-stream`, blocking returns a JSON object." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Pipeline not found", "status": 400 } } } } }, "description": "`invalid_param` : The knowledge base has no processing pipeline configured, or the request body failed validation." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : No knowledge base matches `dataset_id`." }, "500": { "content": { "application/json": { "examples": { "pipeline_run_error": { "summary": "pipeline_run_error", "value": { "code": "pipeline_run_error", "message": "Pipeline execution failed: connection timeout", "status": 500 } } } } }, "description": "`pipeline_run_error` : Pipeline execution failed." } }, "summary": "Run Pipeline", "tags": [ "Knowledge Pipeline" ], "x-mint": { "href": "/en/api-reference/knowledge-pipeline/run-pipeline", "metadata": { "sidebarTitle": "Run Pipeline", "title": "Run Pipeline" } } } }, "/datasets/{dataset_id}/retrieve": { "post": { "description": "Searches a knowledge base and returns the chunks most relevant to the query, for both production retrieval and test retrieval.", "operationId": "retrieveSegments", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachment_ids": { "description": "List of attachment IDs to include in the retrieval context.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "external_retrieval_model": { "description": "Retrieval settings for external knowledge bases.", "properties": { "score_threshold": { "description": "Minimum similarity score threshold for filtering results.", "type": "number" }, "score_threshold_enabled": { "description": "Whether score threshold filtering is enabled.", "type": "boolean" }, "top_k": { "description": "Maximum number of results to return.", "type": "integer" } }, "type": "object" }, "query": { "description": "Search query text.", "maxLength": 250, "type": "string" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." } }, "required": [ "query" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "query": { "content": "What is Dify?" }, "records": [ { "child_chunks": [], "files": [], "score": 0.92, "segment": { "answer": "", "completed_at": 1741267200, "content": "Dify is an open-source LLM app development platform.", "created_at": 1741267200, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "disabled_at": null, "disabled_by": null, "document": { "data_source_type": "upload_file", "doc_metadata": null, "doc_type": null, "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "name": "guide.txt" }, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "enabled": true, "error": null, "hit_count": 1, "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "index_node_hash": "abc123def456", "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "indexing_at": 1741267200, "keywords": [ "dify", "platform", "llm" ], "position": 1, "sign_content": "", "status": "completed", "stopped_at": null, "tokens": 12, "word_count": 9 }, "summary": null, "tsne_position": null } ] } } }, "schema": { "properties": { "query": { "description": "The original query object.", "properties": { "content": { "description": "The query text.", "type": "string" } }, "type": "object" }, "records": { "description": "List of matched retrieval records.", "items": { "properties": { "child_chunks": { "description": "Matched child chunks within the chunk, if using hierarchical indexing.", "items": { "properties": { "content": { "description": "Text content of the child chunk.", "type": "string" }, "id": { "description": "Unique identifier of the child chunk.", "type": "string" }, "position": { "description": "Position of the child chunk within the parent chunk.", "type": "integer" }, "score": { "description": "Similarity score of the child chunk.", "type": "number" } }, "type": "object" }, "type": "array" }, "files": { "description": "Files attached to this chunk.", "items": { "properties": { "extension": { "description": "File extension.", "type": "string" }, "id": { "description": "Attachment file identifier.", "type": "string" }, "mime_type": { "description": "MIME type of the file.", "type": "string" }, "name": { "description": "Original file name.", "type": "string" }, "size": { "description": "File size in bytes.", "type": "integer" }, "source_url": { "description": "URL to access the attachment.", "type": "string" } }, "type": "object" }, "type": "array" }, "score": { "description": "Similarity score.", "type": "number" }, "segment": { "description": "Matched chunk from the knowledge base.", "properties": { "answer": { "description": "Answer content, used in Q&A mode documents.", "type": "string" }, "completed_at": { "description": "Timestamp when indexing completed. `null` if not yet completed.", "nullable": true, "type": "number" }, "content": { "description": "Text content of the chunk.", "type": "string" }, "created_at": { "description": "Creation timestamp (Unix epoch in seconds).", "type": "number" }, "created_by": { "description": "ID of the user who created the chunk.", "type": "string" }, "disabled_at": { "description": "Timestamp when the chunk was disabled. `null` if enabled.", "nullable": true, "type": "number" }, "disabled_by": { "description": "ID of the user who disabled the chunk. `null` if enabled.", "nullable": true, "type": "string" }, "document": { "description": "Parent document information for the matched chunk.", "properties": { "data_source_type": { "description": "How the document was created.", "type": "string" }, "doc_metadata": { "description": "Metadata values for the document. `null` if no metadata is configured.", "nullable": true, "type": "object" }, "doc_type": { "description": "Document type classification. `null` if not set.", "nullable": true, "type": "string" }, "id": { "description": "Unique identifier of the document.", "type": "string" }, "name": { "description": "Document name.", "type": "string" } }, "type": "object" }, "document_id": { "description": "ID of the document this chunk belongs to.", "type": "string" }, "enabled": { "description": "Whether the chunk is enabled for retrieval.", "type": "boolean" }, "error": { "description": "Error message if indexing failed. `null` when no error.", "nullable": true, "type": "string" }, "hit_count": { "description": "Number of times this chunk has been matched in retrieval queries.", "type": "integer" }, "id": { "description": "Unique identifier of the chunk.", "type": "string" }, "index_node_hash": { "description": "Hash of the indexed content, used to detect changes.", "type": "string" }, "index_node_id": { "description": "ID of the index node in the vector store.", "type": "string" }, "indexing_at": { "description": "Timestamp when indexing started. `null` if not yet started.", "nullable": true, "type": "number" }, "keywords": { "description": "Keywords associated with this chunk for keyword-based retrieval.", "items": { "type": "string" }, "type": "array" }, "position": { "description": "Position of the chunk within the document.", "type": "integer" }, "sign_content": { "description": "Signed content hash for integrity verification.", "type": "string" }, "status": { "description": "Indexing status of the chunk.", "type": "string" }, "stopped_at": { "description": "Timestamp when indexing was stopped. `null` if not stopped.", "nullable": true, "type": "number" }, "tokens": { "description": "Token count of the chunk content.", "type": "integer" }, "word_count": { "description": "Word count of the chunk content.", "type": "integer" } }, "type": "object" }, "summary": { "description": "Summary content if retrieved via summary index.", "nullable": true, "type": "string" }, "tsne_position": { "description": "t-SNE visualization position.", "nullable": true, "type": "object" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Retrieval results." }, "400": { "content": { "application/json": { "examples": { "completion_request_error": { "summary": "completion_request_error", "value": { "code": "completion_request_error", "message": "Completion request failed.", "status": 400 } }, "dataset_not_initialized": { "summary": "dataset_not_initialized", "value": { "code": "dataset_not_initialized", "message": "The dataset is still being initialized or indexing. Please wait a moment.", "status": 400 } }, "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Invalid parameter value.", "status": 400 } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted Model Provider has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.", "status": 400 } } } } }, "description": "- `dataset_not_initialized` : The knowledge base is still initializing or indexing.\n- `provider_not_initialize` : The model provider has no valid credentials configured.\n- `provider_quota_exceeded` : The Dify-hosted model provider quota is exhausted.\n- `model_currently_not_support` : The selected model is not currently supported.\n- `completion_request_error` : The model request failed.\n- `invalid_param` : A request parameter is invalid." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.", "status": 403 } }, "forbidden_3": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : Your subscription's knowledge base request rate limit has been reached.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : No knowledge base matches `dataset_id`." }, "500": { "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "An internal error occurred.", "status": 500 } } } } }, "description": "`internal_server_error` : An internal error occurred during retrieval." } }, "summary": "Retrieve Chunks from a Knowledge Base / Test Retrieval", "tags": [ "Knowledge Bases" ], "x-mint": { "href": "/en/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval", "metadata": { "sidebarTitle": "Retrieve Chunks from a Knowledge Base / Test Retrieval", "title": "Retrieve Chunks from a Knowledge Base / Test Retrieval" } } } }, "/datasets/{dataset_id}/tags": { "get": { "description": "Returns the tags bound to a knowledge base.", "operationId": "queryDatasetTags", "parameters": [ { "description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).", "in": "path", "name": "dataset_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs" } ], "total": 1 } } }, "schema": { "properties": { "data": { "description": "List of tags bound to this knowledge base.", "items": { "properties": { "id": { "description": "Tag identifier.", "type": "string" }, "name": { "description": "Tag display name.", "type": "string" } }, "type": "object" }, "type": "array" }, "total": { "description": "Total number of tags bound to this knowledge base.", "type": "integer" } }, "type": "object" } } }, "description": "Tags bound to the knowledge base." }, "403": { "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "code": "forbidden", "message": "Dataset api access is not enabled.", "status": 403 } }, "forbidden_2": { "summary": "forbidden (key scope)", "value": { "code": "forbidden", "message": "The API key is not authorized to access this knowledge base.", "status": 403 } } } } }, "description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Dataset not found.", "status": 404 } } } } }, "description": "`not_found` : Dataset not found." } }, "summary": "Get Knowledge Base Tags", "tags": [ "Tags" ], "x-mint": { "href": "/en/api-reference/tags/get-knowledge-base-tags", "metadata": { "sidebarTitle": "Get Knowledge Base Tags", "title": "Get Knowledge Base Tags" } } } }, "/end-users/{end_user_id}": { "get": { "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns an end user's details by ID. Useful for resolving an end-user ID returned by another endpoint, such as `created_by` in the [Upload File](/en/api-reference/files/upload-file) response.", "operationId": "getEndUserChat", "parameters": [ { "description": "ID of the end user to look up.", "in": "path", "name": "end_user_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "endUserDetail": { "summary": "Response Example", "value": { "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "created_at": "2024-01-16T12:00:29Z", "external_user_id": "abc-123", "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "is_anonymous": false, "name": null, "session_id": "abc-123", "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "type": "service-api", "updated_at": "2024-01-16T12:00:29Z" } } }, "schema": { "$ref": "#/components/schemas/EndUserDetail" } } }, "description": "End user retrieved successfully." }, "404": { "content": { "application/json": { "examples": { "end_user_not_found": { "summary": "end_user_not_found", "value": { "code": "end_user_not_found", "message": "End user not found.", "status": 404 } } } } }, "description": "`end_user_not_found` : End user not found." } }, "summary": "Get End User Info", "tags": [ "End Users" ], "x-mint": { "href": "/en/api-reference/end-users/get-end-user-info", "metadata": { "sidebarTitle": "Get End User Info", "title": "Get End User Info" } } } }, "/files/upload": { "post": { "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nUploads a file and returns its `id` for later requests to reference. The file belongs to the uploading end user: only requests carrying the same `user` can reference it.\n\nWhich file types an app actually consumes depends on its file-upload settings; read them from [Get App Parameters](/en/api-reference/applications/get-app-parameters).", "operationId": "uploadChatFile", "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "The file to upload, as one `multipart/form-data` part. The filename must not contain `/` or `\\`.\n\nAny extension is accepted unless it is on the deployment's security blacklist (`UPLOAD_FILE_EXTENSION_BLACKLIST`, empty by default).\n\nSize limits per category: images 10 MB, audio 50 MB, video 100 MB, other files 15 MB by default (Dify Cloud uses the defaults). Self-hosted deployments adjust them with the `UPLOAD_*_FILE_SIZE_LIMIT` [environment variables](/en/self-host/deploy/configuration/environments).", "format": "binary", "type": "string" }, "user": { "description": "End-user identifier this upload belongs to, defined by your app and unique within it. Omit it to attribute the upload to the shared `DEFAULT-USER`. Only later requests with the same `user` can reference the file. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "File upload request. Requires multipart/form-data.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "uploadSuccess": { "summary": "Response Example", "value": { "conversation_id": null, "created_at": 1705407629, "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "extension": "png", "file_key": null, "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "mime_type": "image/png", "name": "product-photo.png", "original_url": null, "preview_url": null, "reference": null, "size": 204800, "source_url": "https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI=", "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "user_id": null } } }, "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } }, "description": "File uploaded successfully." }, "400": { "content": { "application/json": { "examples": { "file_extension_blocked": { "summary": "file_extension_blocked", "value": { "code": "file_extension_blocked", "message": "The file extension is blocked for security reasons.", "status": 400 } }, "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "code": "filename_not_exists_error", "message": "The specified filename does not exist.", "status": 400 } }, "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Filename contains invalid characters", "status": 400 } }, "no_file_uploaded": { "summary": "no_file_uploaded", "value": { "code": "no_file_uploaded", "message": "Please upload your file.", "status": 400 } }, "too_many_files": { "summary": "too_many_files", "value": { "code": "too_many_files", "message": "Only one file is allowed.", "status": 400 } } } } }, "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `invalid_param` : The filename contains `/` or `\\`.\n- `file_extension_blocked` : The file's extension is on the deployment's security blacklist (see the `file` field)." }, "413": { "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "code": "file_too_large", "message": "", "status": 413 } } } } }, "description": "`file_too_large` : The file exceeds its category's size limit (see the `file` field). The runtime `message` is currently returned as an empty string (a known backend quirk); rely on the `code` and status." }, "415": { "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "code": "unsupported_file_type", "message": "File type not allowed.", "status": 415 } } } } }, "description": "`unsupported_file_type` : The uploaded `file` part declares no MIME type." } }, "summary": "Upload File", "tags": [ "Files" ], "x-mint": { "href": "/en/api-reference/files/upload-file", "metadata": { "sidebarTitle": "Upload File", "title": "Upload File" } } } }, "/files/{file_id}/preview": { "get": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns the raw bytes of a file previously returned by [Upload File](/en/api-reference/files/upload-file). A file is reachable only through the app whose messages reference it.", "operationId": "previewChatFile", "parameters": [ { "description": "ID of the file to download, from the Upload File response.", "in": "path", "name": "file_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "When `true`, the file downloads as an attachment instead of rendering inline in the browser.", "in": "query", "name": "as_attachment", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "End-user identifier, defined by your app and unique within it. It has no effect on file access here, which is scoped by app and message rather than by `user`. See [End User Identity](/en/api-reference/guides/end-user-identity).", "in": "query", "name": "user", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "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`." }, "403": { "content": { "application/json": { "examples": { "file_access_denied": { "summary": "file_access_denied", "value": { "code": "file_access_denied", "message": "Access to the requested file is denied.", "status": 403 } } } } }, "description": "`file_access_denied` : The file exists but belongs to a different app or workspace." }, "404": { "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "code": "file_not_found", "message": "The requested file was not found.", "status": 404 } } } } }, "description": "`file_not_found` : No file with this ID is reachable through this app's messages." } }, "summary": "Download File", "tags": [ "Files" ], "x-mint": { "href": "/en/api-reference/files/download-file", "metadata": { "sidebarTitle": "Download File", "title": "Download File" } } } }, "/form/human_input/{form_token}": { "get": { "description": "**Available for**: Chatflow, Workflow apps.\n\nReturns the contents of a paused Human Input form. Requires web app delivery.\n\nFor the full sequence of Human Input calls, see [Human Input Flow](/en/api-reference/guides/human-input-flow).", "operationId": "getChatflowHumanInputForm", "parameters": [ { "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.", "in": "path", "name": "form_token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "expiration_time": 1745510400, "form_content": "Please review the draft, set a priority, and confirm or request changes.", "inputs": [ { "default": { "selector": [], "type": "constant", "value": "" }, "output_variable_name": "feedback", "type": "paragraph" }, { "option_source": { "selector": [], "type": "constant", "value": [ "low", "medium", "high" ] }, "output_variable_name": "priority", "type": "select" }, { "allowed_file_extensions": [], "allowed_file_types": [ "image", "document" ], "allowed_file_upload_methods": [ "local_file", "remote_url" ], "output_variable_name": "attachment", "type": "file" }, { "allowed_file_extensions": [], "allowed_file_types": [ "image", "document" ], "allowed_file_upload_methods": [ "local_file", "remote_url" ], "number_limits": 5, "output_variable_name": "attachments", "type": "file-list" } ], "resolved_default_values": { "feedback": "" }, "user_actions": [ { "button_style": "primary", "id": "approve", "title": "Approve" }, { "button_style": "default", "id": "reject", "title": "Request changes" } ] } } }, "schema": { "properties": { "expiration_time": { "description": "Unix timestamp (seconds) after which this form can no longer be submitted.", "format": "int64", "nullable": true, "type": "integer" }, "form_content": { "description": "Pre-rendered form body with workflow variables substituted.", "type": "string" }, "inputs": { "description": "Form input field definitions.", "items": { "properties": { "allowed_file_extensions": { "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.", "items": { "type": "string" }, "type": "array" }, "allowed_file_types": { "description": "File categories the recipient may upload. Present for `file` and `file-list` inputs. Values: `image`, `document`, `audio`, `video`, `custom`.", "items": { "enum": [ "image", "document", "audio", "video", "custom" ], "type": "string" }, "type": "array" }, "allowed_file_upload_methods": { "description": "Upload methods the recipient may use. Values: `local_file`, `remote_url`. Present for `file` and `file-list` inputs.", "items": { "enum": [ "local_file", "remote_url" ], "type": "string" }, "type": "array" }, "default": { "description": "Raw default-value configuration for `paragraph` inputs. The client should not resolve this directly; use `resolved_default_values` to display defaults. absent for other input types or when no default is configured.", "nullable": true, "properties": { "selector": { "description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements.", "items": { "type": "string" }, "type": "array" }, "type": { "description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable.", "type": "string" }, "value": { "description": "Literal default value when `type` is `constant`. Always a string.", "type": "string" } }, "type": "object" }, "number_limits": { "description": "Maximum number of files the recipient may upload. Present only for `file-list` inputs.", "type": "integer" }, "option_source": { "description": "Source of options for `select` inputs. Present only when `type` is `select`.", "properties": { "selector": { "description": "Variable reference path when `type` is `variable`.", "items": { "type": "string" }, "type": "array" }, "type": { "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.", "enum": [ "variable", "constant" ], "type": "string" }, "value": { "description": "Literal option list when `type` is `constant`.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "output_variable_name": { "description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object.", "type": "string" }, "type": { "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).", "type": "string" } }, "type": "object" }, "type": "array" }, "resolved_default_values": { "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.", "type": "object" }, "user_actions": { "description": "Available submission actions.", "items": { "properties": { "button_style": { "description": "Visual style of the button. Available values: `primary`, `default`, `accent`, `ghost`.", "type": "string" }, "id": { "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.", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "type": "string" }, "title": { "description": "Button label shown to the recipient.", "maxLength": 100, "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Form contents retrieved successfully." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Form not found", "status": 404 } } } } }, "description": "`not_found` : Form not found." }, "412": { "content": { "application/json": { "examples": { "human_input_form_expired": { "summary": "human_input_form_expired", "value": { "code": "human_input_form_expired", "message": "This form has expired, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": 412 } }, "human_input_form_submitted": { "summary": "human_input_form_submitted", "value": { "code": "human_input_form_submitted", "message": "This form has already been submitted by another user, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": 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." } }, "summary": "Get Human Input Form", "tags": [ "Human Input" ], "x-mint": { "href": "/en/api-reference/human-input/get-human-input-form", "metadata": { "sidebarTitle": "Get Human Input Form", "title": "Get Human Input Form" } } }, "post": { "description": "**Available for**: Chatflow, Workflow apps.\n\nSubmits the recipient's response to a paused Human Input form. On acceptance the workflow resumes; follow the resumed run via [Stream Workflow Events](/en/api-reference/workflow-runs/stream-workflow-events). Requires web app delivery.", "operationId": "submitChatflowHumanInputForm", "parameters": [ { "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.", "in": "path", "name": "form_token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "approve": { "summary": "Request Example", "value": { "action": "approve", "inputs": { "attachment": { "transfer_method": "local_file", "type": "image", "upload_file_id": "3c8fa1b2-7d4e-4f9a-b0c1-d2e3f4a5b6c7" }, "attachments": [ { "transfer_method": "local_file", "type": "document", "upload_file_id": "1a77f0df-c0e6-461c-987c-e72526f341ee" }, { "transfer_method": "remote_url", "type": "document", "url": "https://example.com/report.pdf" } ], "feedback": "Looks good to ship", "priority": "high" }, "user": "abc-123" } } }, "schema": { "properties": { "action": { "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)).", "type": "string" }, "inputs": { "additionalProperties": true, "description": "Submitted values keyed by each input's `output_variable_name`. Paragraph and select inputs take a string; a `file` input takes one file mapping; a `file-list` input takes an array of file mappings.\n\nA file mapping is `{transfer_method: local_file, upload_file_id, type}` or `{transfer_method: remote_url, url, type}`, where `type` is one of the field's `allowed_file_types`. For `local_file`, `upload_file_id` is the `id` from [Upload File](/en/api-reference/files/upload-file).\n\nUse a consistent `user` across the run, upload, and submit.", "type": "object" }, "user": { "description": "End-user identifier, defined by your app and unique within it. Service API and web app user IDs are separate, even when identical. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "required": [ "inputs", "action", "user" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": {} } }, "schema": { "type": "object" } } }, "description": "Form submitted successfully. The response body is an empty object." }, "400": { "content": { "application/json": { "examples": { "bad_request": { "summary": "bad_request", "value": { "code": "bad_request", "message": "Form recipient type is invalid", "status": 400 } }, "invalid_form_data": { "summary": "invalid_form_data", "value": { "code": "invalid_form_data", "message": "Missing required inputs: feedback", "status": 400 } } } } }, "description": "- `bad_request` : Form recipient type is invalid.\n- `invalid_form_data` : Submission failed validation against the form definition." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Form not found", "status": 404 } } } } }, "description": "`not_found` : Form not found." }, "412": { "content": { "application/json": { "examples": { "human_input_form_expired": { "summary": "human_input_form_expired", "value": { "code": "human_input_form_expired", "message": "This form has expired, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": 412 } }, "human_input_form_submitted": { "summary": "human_input_form_submitted", "value": { "code": "human_input_form_submitted", "message": "This form has already been submitted by another user, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": 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." } }, "summary": "Submit Human Input Form", "tags": [ "Human Input" ], "x-mint": { "href": "/en/api-reference/human-input/submit-human-input-form", "metadata": { "sidebarTitle": "Submit Human Input Form", "title": "Submit Human Input Form" } } } }, "/info": { "get": { "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns basic information about the app: name, description, tags, mode, and author.", "operationId": "getChatAppInfo", "responses": { "200": { "content": { "application/json": { "examples": { "appInfo": { "summary": "Response Example", "value": { "author_name": "Dify Team", "description": "A helpful customer service chatbot.", "mode": "chat", "name": "My Chat App", "tags": [ "customer-service", "chatbot" ] } } }, "schema": { "$ref": "#/components/schemas/AppInfoResponse" } } }, "description": "Basic information of the application." }, "400": { "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "code": "app_unavailable", "message": "App unavailable, please check your app configurations.", "status": 400 } } } } }, "description": "`app_unavailable` : The app was deleted while this request was in flight." } }, "summary": "Get App Info", "tags": [ "Applications" ], "x-mint": { "href": "/en/api-reference/applications/get-app-info", "metadata": { "sidebarTitle": "Get App Info", "title": "Get App Info" } } } }, "/messages": { "get": { "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nReturns a conversation's message history, newest first. Pass `first_id` to page backward into older messages.", "operationId": "getConversationHistory", "parameters": [ { "description": "ID of the conversation to read. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).", "in": "query", "name": "conversation_id", "required": true, "schema": { "type": "string" } }, { "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "in": "query", "name": "user", "required": false, "schema": { "type": "string" } }, { "description": "Pagination cursor: the `id` of the first message on the current page. Pass it to fetch the previous (older) page; omit to fetch the latest messages.", "in": "query", "name": "first_id", "required": false, "schema": { "type": "string" } }, { "description": "Number of chat history messages to return per request.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "conversationHistory": { "summary": "Response Example", "value": { "data": [ { "agent_thoughts": [], "answer": "iPhone 13 Pro Max specs are listed here:...", "answer_tokens": 58, "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "created_at": 1705407629, "currency": "USD", "error": null, "extra_contents": [], "feedback": { "rating": "like" }, "id": "9da23599-e713-473b-982c-4328d4f5c78a", "inputs": { "city": "San Francisco" }, "message_files": [], "message_tokens": 100, "parent_message_id": null, "provider_response_latency": 1.234, "query": "What are the specs of the iPhone 13 Pro Max?", "retriever_resources": [], "status": "normal", "total_price": "0.0012825", "total_tokens": 158 } ], "has_more": false, "limit": 20 } } }, "schema": { "$ref": "#/components/schemas/ConversationHistoryResponse" } } }, "description": "Successfully retrieved conversation history." }, "400": { "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "code": "not_chat_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "`not_chat_app` : App mode does not match the API route." }, "404": { "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Conversation Not Exists.", "status": 404 } }, "first_message_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "First Message Not Exists.", "status": 404 } } } } }, "description": "- `not_found` : Conversation does not exist.\n- `not_found` : First message does not exist (invalid `first_id`)." } }, "summary": "List Conversation Messages", "tags": [ "Conversations" ], "x-mint": { "href": "/en/api-reference/conversations/list-conversation-messages", "metadata": { "sidebarTitle": "List Conversation Messages", "title": "List Conversation Messages" } } } }, "/messages/{message_id}/feedbacks": { "post": { "description": "**Available for**: Chatflow, Chatbot, Legacy Agent, Text Generator apps.\n\nRecords a `like` or `dislike` rating, plus an optional comment, on a message. Submitting `null` for `rating` revokes the message's existing feedback.", "operationId": "postChatMessageFeedback", "parameters": [ { "description": "ID of the message to give feedback on. Get message IDs from [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages).", "in": "path", "name": "message_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "likeFeedback": { "summary": "Request Example", "value": { "content": "This answer was very helpful!", "rating": "like", "user": "abc-123" } } }, "schema": { "$ref": "#/components/schemas/MessageFeedbackRequest" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Arg user must be provided.", "status": 400 } } } } }, "description": "`invalid_param` : The required `user` field is omitted, or `rating` is `null` but there is no existing feedback to revoke." }, "404": { "content": { "application/json": { "examples": { "message_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Message Not Exists.", "status": 404 } } } } }, "description": "`not_found` : Message does not exist." } }, "summary": "Submit Message Feedback", "tags": [ "Feedback" ], "x-mint": { "href": "/en/api-reference/feedback/submit-message-feedback", "metadata": { "sidebarTitle": "Submit Message Feedback", "title": "Submit Message Feedback" } } } }, "/messages/{message_id}/suggested": { "get": { "description": "**Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps.\n\nReturns the follow-up questions suggested for a message.", "operationId": "getSuggestedQuestions", "parameters": [ { "description": "ID of the message to get suggestions for. Get it from a chat response or [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages).", "in": "path", "name": "message_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).", "in": "query", "name": "user", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "suggestedQuestions": { "summary": "Response Example", "value": { "data": [ "What colors does the iPhone 13 Pro Max come in?", "How does the battery compare to iPhone 12?", "What is the price range?" ], "result": "success" } } }, "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponse" } } }, "description": "Successfully retrieved suggested questions." }, "400": { "content": { "application/json": { "examples": { "bad_request": { "summary": "bad_request", "value": { "code": "bad_request", "message": "Suggested Questions Is Disabled.", "status": 400 } }, "not_chat_app": { "summary": "not_chat_app", "value": { "code": "not_chat_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Suggested questions feature is disabled." }, "404": { "content": { "application/json": { "examples": { "message_not_exists": { "summary": "not_found", "value": { "code": "not_found", "message": "Message Not Exists.", "status": 404 } } } } }, "description": "`not_found` : Message does not exist." }, "500": { "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "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.", "status": 500 } } } } }, "description": "`internal_server_error` : Internal server error." } }, "summary": "Get Next Suggested Questions", "tags": [ "Chat Messages" ], "x-mint": { "href": "/en/api-reference/chat-messages/get-next-suggested-questions", "metadata": { "sidebarTitle": "Get Next Suggested Questions", "title": "Get Next Suggested Questions" } } } }, "/meta": { "get": { "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns the display icons for the tools this app uses, keyed by tool name.", "operationId": "getChatAppMeta", "responses": { "200": { "content": { "application/json": { "examples": { "appMeta": { "summary": "Response Example", "value": { "tool_icons": { "calculator": { "background": "#4A90D9", "content": "🧮" }, "dalle3": "https://example.com/icons/dalle3.png" } } } }, "schema": { "$ref": "#/components/schemas/AppMetaResponse" } } }, "description": "Successfully retrieved application meta information." }, "400": { "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "code": "app_unavailable", "message": "App unavailable, please check your app configurations.", "status": 400 } } } } }, "description": "`app_unavailable` : The app was deleted while this request was in flight." } }, "summary": "Get App Meta", "tags": [ "Applications" ], "x-mint": { "href": "/en/api-reference/applications/get-app-meta", "metadata": { "sidebarTitle": "Get App Meta", "title": "Get App Meta" } } } }, "/parameters": { "get": { "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns the app's front-end configuration: the opening statement and suggested questions, feature toggles, the user input form, and file-upload limits. Use it to render the app's inputs and apply the correct upload limits.", "operationId": "getChatAppParameters", "responses": { "200": { "content": { "application/json": { "examples": { "appParameters": { "summary": "Response Example", "value": { "annotation_reply": { "enabled": false }, "file_upload": { "image": { "detail": "high", "enabled": true, "number_limits": 3, "transfer_methods": [ "remote_url", "local_file" ] } }, "more_like_this": { "enabled": false }, "opening_statement": "Hello! How can I help you today?", "retriever_resource": { "enabled": true }, "sensitive_word_avoidance": { "enabled": false }, "speech_to_text": { "enabled": false }, "suggested_questions": [ "What can you do?", "Tell me about your features." ], "suggested_questions_after_answer": { "enabled": true }, "system_parameters": { "audio_file_size_limit": 50, "file_size_limit": 15, "image_file_size_limit": 10, "video_file_size_limit": 100, "workflow_file_upload_limit": 10 }, "text_to_speech": { "autoPlay": "disabled", "enabled": false, "language": "en-US", "voice": "alloy" }, "user_input_form": [ { "text-input": { "default": "", "label": "City", "required": true, "variable": "city" } } ] } } }, "schema": { "$ref": "#/components/schemas/AppParametersResponse" } } }, "description": "Application parameters information." }, "400": { "content": { "application/json": { "examples": { "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 } }, "app_unavailable": { "summary": "app_unavailable", "value": { "code": "app_unavailable", "message": "App unavailable, please check your app configurations.", "status": 400 } } } } }, "description": "- `app_unavailable` : The app is unavailable or misconfigured.\n- `agent_not_published` : The app's Agent has no published version yet. (Agent apps)" } }, "summary": "Get App Parameters", "tags": [ "Applications" ], "x-mint": { "href": "/en/api-reference/applications/get-app-parameters", "metadata": { "sidebarTitle": "Get App Parameters", "title": "Get App Parameters" } } } }, "/site": { "get": { "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nReturns the branding and display settings for the app's hosted web app, such as its title, icon, theme colors, and default language.", "operationId": "getChatWebAppSettings", "responses": { "200": { "content": { "application/json": { "examples": { "webAppSettings": { "summary": "Response Example", "value": { "chat_color_theme": "#4A90D9", "chat_color_theme_inverted": false, "copyright": "2025 Dify", "custom_disclaimer": "", "default_language": "en-US", "description": "A helpful customer service chatbot.", "icon": "🤖", "icon_background": "#FFFFFF", "icon_type": "emoji", "icon_url": null, "input_placeholder": "Ask me anything about our products...", "privacy_policy": "https://example.com/privacy", "show_workflow_steps": false, "title": "My Chat App", "use_icon_as_answer_icon": true } } }, "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" } } }, "description": "Web app settings of the application." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden", "value": { "code": "forbidden", "message": "You don't have the permission to access the requested resource. It is either read-protected or not readable by the server.", "status": 403 } } } } }, "description": "`forbidden` : Site not found for this application or the workspace has been archived." } }, "summary": "Get App WebApp Settings", "tags": [ "Applications" ], "x-mint": { "href": "/en/api-reference/applications/get-app-webapp-settings", "metadata": { "sidebarTitle": "Get App WebApp Settings", "title": "Get App WebApp Settings" } } } }, "/text-to-audio": { "post": { "description": "**Available for**: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.\n\nConverts text to speech audio. Pass `text` to synthesize arbitrary text, or `message_id` to voice an existing message's answer.", "operationId": "textToAudioChat", "requestBody": { "content": { "application/json": { "examples": { "textToAudioExample": { "summary": "Request Example", "value": { "streaming": false, "text": "Hello, welcome to our service.", "user": "abc-123", "voice": "alloy" } } }, "schema": { "$ref": "#/components/schemas/TextToAudioRequest" } } }, "required": true }, "responses": { "200": { "content": { "audio/aac": { "schema": { "format": "binary", "type": "string" } }, "audio/flac": { "schema": { "format": "binary", "type": "string" } }, "audio/mp4": { "schema": { "format": "binary", "type": "string" } }, "audio/mpeg": { "schema": { "format": "binary", "type": "string" } }, "audio/ogg": { "schema": { "format": "binary", "type": "string" } }, "audio/wav": { "schema": { "format": "binary", "type": "string" } }, "audio/webm": { "schema": { "format": "binary", "type": "string" } } }, "description": "Returns the generated audio. The `Content-Type` header reflects the provider's audio container, verified from the response bytes when recognizable.\n\nThe body can be AAC, FLAC, MP4, MP3, Ogg, WAV, or WebM. Output that cannot be recognized is labeled with the provider's declared type, or `audio/mpeg` when none is declared.\n\nStreamed provider output is delivered with chunked transfer encoding; the request `streaming` field does not control this." }, "400": { "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "code": "app_unavailable", "message": "App unavailable, please check your app configurations.", "status": 400 } }, "completion_request_error": { "summary": "completion_request_error", "value": { "code": "completion_request_error", "message": "Completion request failed.", "status": 400 } }, "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "TTS is not enabled", "status": 400 } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "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.", "status": 400 } } } } }, "description": "- `app_unavailable` : The app is unavailable or misconfigured.\n- `invalid_param` : Text-to-speech is not enabled, `text` is missing, or no voice is available.\n- `provider_not_initialize` : No valid model provider credentials are configured.\n- `provider_quota_exceeded` : The model provider quota is exhausted.\n- `model_currently_not_support` : The current model does not support this operation.\n- `completion_request_error` : The text-to-speech request failed." }, "500": { "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "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.", "status": 500 } } } } }, "description": "`internal_server_error` : Internal server error." } }, "summary": "Convert Text to Audio", "tags": [ "Audio" ], "x-mint": { "href": "/en/api-reference/audio/convert-text-to-audio", "metadata": { "sidebarTitle": "Convert Text to Audio", "title": "Convert Text to Audio" } } } }, "/workflow/{workflow_run_id}/events": { "get": { "description": "**Available for**: Chatflow, Workflow apps.\n\nResume the [Server-Sent Events stream](/en/api-reference/guides/streaming) 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": [ { "description": "Workflow run ID whose event stream to resume, from the response or streaming events of [Run Workflow](/en/api-reference/workflow-runs/run-workflow).", "in": "path", "name": "workflow_run_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "End-user identifier, defined by your app and unique within it. Must match the `user` that started the run. See [End User Identity](/en/api-reference/guides/end-user-identity).", "in": "query", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "When `true`, replay from the persisted state snapshot to include a status summary of already-executed nodes before streaming new events.", "in": "query", "name": "include_state_snapshot", "required": false, "schema": { "default": false, "type": "boolean" } }, { "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.", "in": "query", "name": "continue_on_pause", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "text/event-stream": { "examples": { "resumedRun": { "summary": "Response Example - Resumed run (Workflow)", "value": "event: ping\n\ndata: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\", \"submitted_data\": {\"comment\": \"Looks good.\"}}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_2\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 2, \"created_at\": 1705407705}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Approved, now translating.\", \"node_id\": \"node_1\", \"is_final\": false}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}}\n\ndata: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour\"}, \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}" }, "resumedRunChatflow": { "summary": "Response Example - Resumed run (Chatflow)", "value": "event: ping\n\ndata: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\", \"submitted_data\": {\"comment\": \"Looks good.\"}}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"created_at\": 1705407705}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"The reviewer approved the draft.\", \"node_id\": \"node_llm_1\", \"is_final\": false}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}}\n\ndata: {\"event\": \"message\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"answer\": \"Approved\", \"created_at\": 1705407706}\n\ndata: {\"event\": \"node_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"status\": \"succeeded\", \"elapsed_time\": 1.2, \"created_at\": 1705407705, \"finished_at\": 1705407706}}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"metadata\": {\"usage\": {\"total_tokens\": 42, \"latency\": 1.3}}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}" } }, "schema": { "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.", "type": "string" } } }, "description": "Server-Sent Events stream. It opens with a bare `event: ping` frame (keep-alive; more arrive roughly every 10 seconds); every other event is delivered as `data: {JSON}\\n\\n`. Event payloads follow the same schemas as the original streaming response." }, "400": { "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "`not_workflow_app` : Please check if your app mode matches the right API route." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Workflow run not found", "status": 404 } } } } }, "description": "`not_found` : Workflow run not found." } }, "summary": "Stream Workflow Events", "tags": [ "Workflow Runs" ], "x-mint": { "href": "/en/api-reference/workflow-runs/stream-workflow-events", "metadata": { "sidebarTitle": "Stream Workflow Events", "title": "Stream Workflow Events" } } } }, "/workflows/logs": { "get": { "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", "parameters": [ { "description": "Keyword to search in logs.", "in": "query", "name": "keyword", "schema": { "type": "string" } }, { "description": "Filter by execution status.", "in": "query", "name": "status", "schema": { "enum": [ "succeeded", "failed", "stopped" ], "type": "string" } }, { "description": "Page number.", "in": "query", "name": "page", "schema": { "default": 1, "maximum": 99999, "minimum": 1, "type": "integer" } }, { "description": "Number of items per page.", "in": "query", "name": "limit", "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Filter logs created before this ISO 8601 timestamp.", "in": "query", "name": "created_at__before", "schema": { "format": "date-time", "type": "string" } }, { "description": "Filter logs created after this ISO 8601 timestamp.", "in": "query", "name": "created_at__after", "schema": { "format": "date-time", "type": "string" } }, { "description": "Filter by end user session ID.", "in": "query", "name": "created_by_end_user_session_id", "schema": { "type": "string" } }, { "description": "Filter by the creator's account email (e.g., `name@example.com`).", "in": "query", "name": "created_by_account", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "workflowLogs": { "summary": "Response Example", "value": { "data": [ { "created_at": 1705407629, "created_by_account": null, "created_by_end_user": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "is_anonymous": false, "session_id": "user_workflow_123", "type": "service-api" }, "created_by_role": "end_user", "created_from": "service-api", "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", "workflow_run": { "created_at": 1705407629, "elapsed_time": 1.23, "error": null, "exceptions_count": 0, "finished_at": 1705407630, "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "status": "succeeded", "total_steps": 3, "total_tokens": 150, "triggered_from": "app-run", "version": "2025-01-16 12:00:00.000000" } } ], "has_more": false, "limit": 20, "page": 1, "total": 1 } } }, "schema": { "$ref": "#/components/schemas/WorkflowLogsResponse" } } }, "description": "Successfully retrieved workflow logs." }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Account not found: name@example.com", "status": 400 } } } } }, "description": "`invalid_param` : A query parameter is invalid, such as a `created_by_account` value matching no account, a malformed `created_at__before` or `created_at__after` timestamp, or an out-of-range `page`, `limit`, or `status` value." } }, "summary": "List Workflow Logs", "tags": [ "Workflow Runs" ], "x-mint": { "href": "/en/api-reference/workflow-runs/list-workflow-logs", "metadata": { "sidebarTitle": "List Workflow Logs", "title": "List Workflow Logs" } } } }, "/workflows/run": { "post": { "description": "**Available for**: Workflow apps.\n\nRun the app's published workflow and return its outputs, either in a single `blocking` response or as a `streaming` Server-Sent Events feed. Requires a published workflow.", "operationId": "executeWorkflow", "requestBody": { "content": { "application/json": { "examples": { "blocking_example": { "summary": "Request Example - Blocking mode", "value": { "inputs": { "query": "Translate this to French: Hello world" }, "response_mode": "blocking", "user": "user_workflow_456" } }, "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" } }, "with_file_array_variable": { "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "transfer_method": "local_file", "type": "document", "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "transfer_method": "remote_url", "type": "image", "url": "https://example.com/image.jpg" } ] }, "response_mode": "blocking", "user": "user_workflow_789" } } }, "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "blockingResponse": { "summary": "Response Example - Blocking mode", "value": { "data": { "created_at": 1705407629, "elapsed_time": 1.23, "error": null, "finished_at": 1705407630, "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "outputs": { "result": "Bonjour le monde" }, "status": "succeeded", "total_steps": 3, "total_tokens": 150, "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345" }, "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156" } } }, "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" } }, "text/event-stream": { "examples": { "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}}\n\ndata: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}}\n\ndata: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" }, "streamingResponse": { "summary": "Response Example - Streaming mode", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}}\n\ndata: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" } }, "schema": { "description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive; the stream opens with one, then more arrive roughly every 10 seconds).\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries `message_id: null` and no `conversation_id`. The parallel `text_chunk` stream stays free of `` tags.\n\n**Human Input events**:\n- `human_input_required`: Fires together with `workflow_paused` when the workflow reaches a Human Input node. Use the `form_token` from the payload to drive the form-handling flow via the [Human Input API](/en/api-reference/human-input/get-human-input-form).\n- `human_input_form_filled`: A recipient submitted the form; workflow execution resumes.\n- `human_input_form_timeout`: The form expired without a response. Workflow follows the timeout fallback edge if defined.", "type": "string" } } }, "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." }, "400": { "content": { "application/json": { "examples": { "completion_request_error": { "summary": "completion_request_error", "value": { "code": "completion_request_error", "message": "Completion request failed.", "status": 400 } }, "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Arg user must be provided.", "status": 400 } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model.", "status": 400 } }, "not_workflow_app": { "summary": "not_workflow_app", "value": { "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "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.", "status": 400 } } } } }, "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : A request parameter is missing or invalid, such as a missing `user` or an unpublished workflow." }, "403": { "content": { "application/json": { "examples": { "trigger_workflow_service_mode_unavailable": { "summary": "trigger_workflow_service_mode_unavailable", "value": { "code": "trigger_workflow_service_mode_unavailable", "message": "This workflow uses a trigger entry and cannot be invoked through Web App, Service API, OpenAPI, or MCP.", "status": 403 } } } } }, "description": "`trigger_workflow_service_mode_unavailable` : The workflow starts from a trigger node, so it runs only from its trigger events. Only workflows that start from a User Input node can be run through the API." }, "429": { "content": { "application/json": { "examples": { "rate_limit_error": { "summary": "rate_limit_error", "value": { "code": "rate_limit_error", "message": "Workflow execution quota limit reached for tenant 8f1e2a90-3b7c-4d55-9a01-6c2f4e8b1d33", "status": 429 } }, "too_many_requests": { "summary": "too_many_requests", "value": { "code": "too_many_requests", "message": "Too many requests. Please try again later.", "status": 429 } } } } }, "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached." }, "500": { "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal Server Error.", "status": 500 } } } } }, "description": "`internal_server_error` : Internal server error." } }, "summary": "Run Workflow", "tags": [ "Workflow Runs" ], "x-mint": { "href": "/en/api-reference/workflow-runs/run-workflow", "metadata": { "sidebarTitle": "Run Workflow", "title": "Run Workflow" } } } }, "/workflows/run/{workflow_run_id}": { "get": { "description": "**Available for**: Chatflow, Workflow apps.\n\nGet a single workflow run's status, inputs, outputs, and execution metrics.", "operationId": "getWorkflowRunDetail", "parameters": [ { "description": "Workflow run ID, from the response or streaming events of [Run Workflow](/en/api-reference/workflow-runs/run-workflow), or from message metadata in Chatflow apps.", "in": "path", "name": "workflow_run_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "workflowRunDetail": { "summary": "Response Example", "value": { "created_at": 1705407629, "elapsed_time": 1.23, "error": null, "finished_at": 1705407630, "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "inputs": "{\"query\": \"Translate this to French\"}", "outputs": { "result": "Traduisez ceci en francais" }, "status": "succeeded", "total_steps": 3, "total_tokens": 150, "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345" } } }, "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponse" } } }, "description": "Successfully retrieved workflow run details." }, "400": { "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "`not_workflow_app` : App mode does not match the API route." }, "404": { "content": { "application/json": { "examples": { "workflow_run_not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Workflow run not found.", "status": 404 } } } } }, "description": "`not_found` : Workflow run not found." } }, "summary": "Get Workflow Run Detail", "tags": [ "Workflow Runs" ], "x-mint": { "href": "/en/api-reference/workflow-runs/get-workflow-run-detail", "metadata": { "sidebarTitle": "Get Workflow Run Detail", "title": "Get Workflow Run Detail" } } } }, "/workflows/tasks/{task_id}/stop": { "post": { "description": "**Available for**: Workflow apps.\n\nStop a running workflow task. Only supported in `streaming` mode.", "operationId": "stopWorkflowTaskGeneration", "parameters": [ { "description": "Task ID, from the streaming events of [Run Workflow](/en/api-reference/workflow-runs/run-workflow).", "in": "path", "name": "task_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Request Example", "value": { "user": "user_workflow_123" } } }, "schema": { "properties": { "user": { "description": "End-user identifier, defined by your app and unique within it. Need not match the `user` that started the run; the stop applies to the task regardless of `user`. See [End User Identity](/en/api-reference/guides/end-user-identity).", "type": "string" } }, "required": [ "user" ], "type": "object" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Arg user must be provided.", "status": 400 } }, "not_workflow_app": { "summary": "not_workflow_app", "value": { "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } } } } }, "description": "- `not_workflow_app` : App mode does not match the API route.\n- `invalid_param` : A request parameter is missing or invalid, such as a missing `user`." } }, "summary": "Stop Workflow Task", "tags": [ "Workflow Runs" ], "x-mint": { "href": "/en/api-reference/workflow-runs/stop-workflow-task", "metadata": { "sidebarTitle": "Stop Workflow Task", "title": "Stop Workflow Task" } } } }, "/workflows/{workflow_id}/run": { "post": { "description": "**Available for**: Workflow apps.\n\nRun a specific published workflow version, identified by the `workflow_id` in the path. Request body, response, and streaming behavior match [Run Workflow](/en/api-reference/workflow-runs/run-workflow); only the executed version differs.", "operationId": "runWorkflowById", "parameters": [ { "description": "Published workflow version to run. Returned in the `workflow_id` field of [Run Workflow](/en/api-reference/workflow-runs/run-workflow) responses and [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail). Must reference a published version; a draft version ID is rejected with `bad_request`.", "in": "path", "name": "workflow_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Request Example", "value": { "inputs": { "query": "Summarize this article" }, "response_mode": "blocking", "user": "user_workflow_123" } } }, "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "blockingResponse": { "summary": "Response Example - Blocking mode", "value": { "data": { "created_at": 1705407629, "elapsed_time": 2.45, "error": null, "finished_at": 1705407631, "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "outputs": { "result": "Article summary here" }, "status": "succeeded", "total_steps": 4, "total_tokens": 280, "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345" }, "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156" } } }, "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" } }, "text/event-stream": { "examples": { "humanInputPause": { "summary": "Response Example - Human Input pause", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}}\n\ndata: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}}\n\ndata: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" }, "streamingResponse": { "summary": "Response Example - Streaming mode", "value": "event: ping\n\ndata: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}}\n\ndata: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}}\n\ndata: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" } }, "schema": { "description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive; the stream opens with one, then more arrive roughly every 10 seconds).\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries `message_id: null` and no `conversation_id`. The parallel `text_chunk` stream stays free of `` tags.\n\n**Human Input events**:\n- `human_input_required`: Fires together with `workflow_paused` when the workflow reaches a Human Input node. Use the `form_token` from the payload to drive the form-handling flow via the [Human Input API](/en/api-reference/human-input/get-human-input-form).\n- `human_input_form_filled`: A recipient submitted the form; workflow execution resumes.\n- `human_input_form_timeout`: The form expired without a response. Workflow follows the timeout fallback edge if defined.", "type": "string" } } }, "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." }, "400": { "content": { "application/json": { "examples": { "bad_request": { "summary": "bad_request", "value": { "code": "bad_request", "message": "Cannot use draft workflow version. Workflow ID: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345. Please use a published workflow version or leave workflow_id empty.", "status": 400 } }, "completion_request_error": { "summary": "completion_request_error", "value": { "code": "completion_request_error", "message": "Completion request failed.", "status": 400 } }, "invalid_param": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Arg user must be provided.", "status": 400 } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model.", "status": 400 } }, "not_workflow_app": { "summary": "not_workflow_app", "value": { "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route.", "status": 400 } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.", "status": 400 } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "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.", "status": 400 } } } } }, "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : A request parameter is missing or invalid, such as a missing `user`." }, "403": { "content": { "application/json": { "examples": { "trigger_workflow_service_mode_unavailable": { "summary": "trigger_workflow_service_mode_unavailable", "value": { "code": "trigger_workflow_service_mode_unavailable", "message": "This workflow uses a trigger entry and cannot be invoked through Web App, Service API, OpenAPI, or MCP.", "status": 403 } }, "workflow_version_execution_not_allowed": { "summary": "workflow_version_execution_not_allowed", "value": { "code": "workflow_version_execution_not_allowed", "message": "Workflow version execution is not available on your current plan. Please upgrade to a paid plan.", "status": 403 } } } } }, "description": "- `workflow_version_execution_not_allowed` : Executing a specific workflow version is not available on the Dify Cloud Sandbox plan.\n- `trigger_workflow_service_mode_unavailable` : The selected workflow version starts from a trigger node, so it runs only from its trigger events. Only the selected version is checked, so a version that starts from a User Input node can still be run by ID." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "code": "not_found", "message": "Workflow not found with id: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": 404 } } } } }, "description": "`not_found` : Workflow not found." }, "429": { "content": { "application/json": { "examples": { "rate_limit_error": { "summary": "rate_limit_error", "value": { "code": "rate_limit_error", "message": "Workflow execution quota limit reached for tenant 8f1e2a90-3b7c-4d55-9a01-6c2f4e8b1d33", "status": 429 } }, "too_many_requests": { "summary": "too_many_requests", "value": { "code": "too_many_requests", "message": "Too many requests. Please try again later.", "status": 429 } } } } }, "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached." }, "500": { "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "code": "internal_server_error", "message": "Internal Server Error.", "status": 500 } } } } }, "description": "`internal_server_error` : Internal server error." } }, "summary": "Run Workflow by ID", "tags": [ "Workflow Runs" ], "x-mint": { "href": "/en/api-reference/workflow-runs/run-workflow-by-id", "metadata": { "sidebarTitle": "Run Workflow by ID", "title": "Run Workflow by ID" } } } }, "/workspaces/current/models/model-types/{model_type}": { "get": { "description": "Returns the available models of a given type. Use it to find the `text-embedding` and `rerank` models to configure on a knowledge base.", "operationId": "getAvailableModels", "parameters": [ { "description": "Type of model to retrieve. For knowledge base configuration, use `text-embedding` for embedding models or `rerank` for reranking models.", "in": "path", "name": "model_type", "required": true, "schema": { "enum": [ "text-embedding", "rerank", "llm", "tts", "speech2text", "moderation" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "success": { "summary": "Response Example", "value": { "data": [ { "icon_small": { "en_US": "https://example.com/openai-small.svg", "zh_Hans": "https://example.com/openai-small.svg" }, "icon_small_dark": null, "label": { "en_US": "OpenAI", "zh_Hans": "OpenAI" }, "models": [ { "deprecated": false, "features": null, "fetch_from": "predefined-model", "has_invalid_load_balancing_configs": false, "label": { "en_US": "text-embedding-3-small", "zh_Hans": "text-embedding-3-small" }, "load_balancing_enabled": false, "model": "text-embedding-3-small", "model_properties": { "context_size": 8191 }, "model_type": "text-embedding", "status": "active" } ], "provider": "langgenius/openai/openai", "status": "active", "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00" } ] } } }, "schema": { "properties": { "data": { "description": "List of model providers with their available models.", "items": { "properties": { "icon_small": { "description": "URL of the provider's small icon.", "properties": { "en_US": { "description": "Small icon URL.", "type": "string" }, "zh_Hans": { "description": "Chinese icon URL.", "type": "string" } }, "type": "object" }, "icon_small_dark": { "description": "Dark-mode icon URLs; `null` when the provider has none.", "properties": { "en_US": { "type": "string" }, "zh_Hans": { "type": "string" } }, "type": "object" }, "label": { "description": "Localized display name of the provider.", "properties": { "en_US": { "description": "English display name.", "type": "string" }, "zh_Hans": { "description": "Chinese display name.", "type": "string" } }, "type": "object" }, "models": { "description": "List of available models from this provider.", "items": { "properties": { "deprecated": { "description": "Whether the model is deprecated.", "type": "boolean" }, "features": { "description": "Supported features of the model, `null` if none.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "fetch_from": { "description": "Where the model definition comes from. `predefined-model` for built-in models, `customizable-model` for user-configured models.", "type": "string" }, "has_invalid_load_balancing_configs": { "description": "Whether the model has invalid load-balancing configurations.", "type": "boolean" }, "label": { "description": "Localized display name of the model.", "properties": { "en_US": { "description": "English model name.", "type": "string" }, "zh_Hans": { "description": "Chinese model name.", "type": "string" } }, "type": "object" }, "load_balancing_enabled": { "description": "Whether load balancing is enabled for the model.", "type": "boolean" }, "model": { "description": "Model identifier. Use this as the `embedding_model` value when creating or updating a knowledge base.", "type": "string" }, "model_properties": { "description": "Model-specific properties such as `context_size`.", "type": "object" }, "model_type": { "description": "Type of the model, matching the `model_type` path parameter.", "type": "string" }, "status": { "description": "Model availability status. `active` when ready to use.", "type": "string" } }, "type": "object" }, "type": "array" }, "provider": { "description": "Model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). Legacy providers may return the bare short form (e.g. `openai`).", "type": "string" }, "status": { "description": "Provider status. `active` when credentials are configured and valid.", "type": "string" }, "tenant_id": { "description": "Workspace ID the provider configuration belongs to.", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Available models for the specified type." } }, "summary": "Get Available Models", "tags": [ "Models" ], "x-mint": { "href": "/en/api-reference/models/get-available-models", "metadata": { "sidebarTitle": "Get Available Models", "title": "Get Available Models" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "servers": [ { "description": "Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL.", "url": "https://{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." } } } ], "tags": [ { "description": "Operations related to chat messages and interactions.", "name": "Chat Messages" }, { "description": "File upload and preview operations.", "name": "Files" }, { "description": "Operations related to end user information.", "name": "End Users" }, { "description": "User feedback operations.", "name": "Feedback" }, { "description": "Operations related to managing conversations.", "name": "Conversations" }, { "description": "Text-to-Speech and Speech-to-Text operations.", "name": "Audio" }, { "description": "Operations to retrieve application settings and information.", "name": "Applications" }, { "description": "Operations related to managing annotations for direct replies.", "name": "Annotations" }, { "description": "Endpoints for resuming paused workflows that require human input.", "name": "Human Input" }, { "description": "Operations for executing and managing workflows.", "name": "Workflow Runs" }, { "description": "Operations related to text generation and completion.", "name": "Completion Messages" }, { "description": "Operations for managing knowledge bases, including creation, configuration, and retrieval.", "name": "Knowledge Bases" }, { "description": "Operations for creating, updating, and managing documents within a knowledge base.", "name": "Documents" }, { "description": "Operations for managing document chunks and child chunks.", "name": "Chunks" }, { "description": "Operations for managing knowledge base metadata fields and document metadata values.", "name": "Metadata" }, { "description": "Operations for managing knowledge base tags and tag bindings.", "name": "Tags" }, { "description": "Operations for retrieving available models.", "name": "Models" }, { "description": "Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution.", "name": "Knowledge Pipeline" } ] }