mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-07-22 12:25:45 -04:00
Riskey
19466 lines
754 KiB
JSON
19466 lines
754 KiB
JSON
{
|
|
"openapi": "3.0.1",
|
|
"info": {
|
|
"title": "Dify Service API",
|
|
"description": "REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key.",
|
|
"version": "1.0.0"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://{api_base_url}",
|
|
"description": "Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL.",
|
|
"variables": {
|
|
"api_base_url": {
|
|
"default": "api.dify.ai/v1",
|
|
"description": "Host and path of the API base URL, without the `https://` prefix."
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"ApiKeyAuth": []
|
|
}
|
|
],
|
|
"tags": [
|
|
{
|
|
"name": "Chat Messages",
|
|
"description": "Operations related to chat messages and interactions."
|
|
},
|
|
{
|
|
"name": "Files",
|
|
"description": "File upload and preview operations."
|
|
},
|
|
{
|
|
"name": "End Users",
|
|
"description": "Operations related to end user information."
|
|
},
|
|
{
|
|
"name": "Feedback",
|
|
"description": "User feedback operations."
|
|
},
|
|
{
|
|
"name": "Conversations",
|
|
"description": "Operations related to managing conversations."
|
|
},
|
|
{
|
|
"name": "Audio",
|
|
"description": "Text-to-Speech and Speech-to-Text operations."
|
|
},
|
|
{
|
|
"name": "Applications",
|
|
"description": "Operations to retrieve application settings and information."
|
|
},
|
|
{
|
|
"name": "Annotations",
|
|
"description": "Operations related to managing annotations for direct replies."
|
|
},
|
|
{
|
|
"name": "Human Input",
|
|
"description": "Endpoints for resuming paused workflows that require human input."
|
|
},
|
|
{
|
|
"name": "Workflow Runs",
|
|
"description": "Operations for executing and managing workflows."
|
|
},
|
|
{
|
|
"name": "Completion Messages",
|
|
"description": "Operations related to text generation and completion."
|
|
},
|
|
{
|
|
"name": "Knowledge Bases",
|
|
"description": "Operations for managing knowledge bases, including creation, configuration, and retrieval."
|
|
},
|
|
{
|
|
"name": "Documents",
|
|
"description": "Operations for creating, updating, and managing documents within a knowledge base."
|
|
},
|
|
{
|
|
"name": "Chunks",
|
|
"description": "Operations for managing document chunks and child chunks."
|
|
},
|
|
{
|
|
"name": "Metadata",
|
|
"description": "Operations for managing knowledge base metadata fields and document metadata values."
|
|
},
|
|
{
|
|
"name": "Tags",
|
|
"description": "Operations for managing knowledge base tags and tag bindings."
|
|
},
|
|
{
|
|
"name": "Models",
|
|
"description": "Operations for retrieving available models."
|
|
},
|
|
{
|
|
"name": "Knowledge Pipeline",
|
|
"description": "Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution."
|
|
}
|
|
],
|
|
"paths": {
|
|
"/chat-messages": {
|
|
"post": {
|
|
"summary": "Send Chat Message",
|
|
"description": "**Available for**: Chatflow, New Agent, Chatbot, Agent apps.\n\nSends a message to a chat app and returns the assistant's reply. The events in the streaming response vary by app type.",
|
|
"operationId": "sendChatMessage",
|
|
"tags": [
|
|
"Chat Messages"
|
|
],
|
|
"requestBody": {
|
|
"description": "Request body to send a chat message.",
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ChatRequest"
|
|
},
|
|
"examples": {
|
|
"streaming_example": {
|
|
"summary": "Request Example - Streaming mode",
|
|
"value": {
|
|
"inputs": {
|
|
"city": "San Francisco"
|
|
},
|
|
"query": "What are the specs of the iPhone 13 Pro Max?",
|
|
"response_mode": "streaming",
|
|
"conversation_id": "",
|
|
"user": "abc-123",
|
|
"files": [
|
|
{
|
|
"type": "image",
|
|
"transfer_method": "remote_url",
|
|
"url": "https://cloud.dify.ai/logo/logo-site.png"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"blocking_example": {
|
|
"summary": "Request Example - Blocking mode",
|
|
"value": {
|
|
"inputs": {},
|
|
"query": "What are the specs of the iPhone 13 Pro Max?",
|
|
"response_mode": "blocking",
|
|
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
|
|
"user": "abc-123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of Server-Sent Events.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ChatCompletionResponse"
|
|
},
|
|
"examples": {
|
|
"blockingResponse": {
|
|
"summary": "Response Example - Blocking mode",
|
|
"value": {
|
|
"event": "message",
|
|
"task_id": "c3800678-a077-43df-a102-53f23ed20b88",
|
|
"id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e",
|
|
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
|
|
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
|
|
"mode": "chat",
|
|
"answer": "iPhone 13 Pro Max specs are listed here:...",
|
|
"metadata": {
|
|
"usage": {
|
|
"prompt_tokens": 1033,
|
|
"prompt_unit_price": "0.001",
|
|
"prompt_price_unit": "0.001",
|
|
"prompt_price": "0.0010330",
|
|
"completion_tokens": 128,
|
|
"completion_unit_price": "0.002",
|
|
"completion_price_unit": "0.001",
|
|
"completion_price": "0.0002560",
|
|
"total_tokens": 1161,
|
|
"total_price": "0.0012890",
|
|
"currency": "USD",
|
|
"latency": 0.7682376249867957
|
|
},
|
|
"retriever_resources": [
|
|
{
|
|
"position": 1,
|
|
"dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
|
|
"dataset_name": "iPhone",
|
|
"document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00",
|
|
"document_name": "iPhone List",
|
|
"segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a",
|
|
"score": 0.98457545,
|
|
"content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""
|
|
}
|
|
]
|
|
},
|
|
"created_at": 1705407629
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"text/event-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive every 10 seconds).\n\n**Events by app type** (the reply events, then how the stream closes):\n\n- **Chatbot**: `message` chunks (concatenate in order) → `message_end`.\n- **Agent**: `agent_thought` reasoning and tool-call steps alongside `agent_message` chunks → `message_end`.\n- **New Agent**: `agent_message` chunks with `agent_thought` steps alongside → one closing `message` carrying the complete answer (treat it as the final answer, not extra text to append) → `message_end`. Its `message_end` metadata carries `usage` (plus `annotation_reply` on an annotation match) and never `retriever_resources`.\n- **Chatflow**: `workflow_started` → node events (`node_started`, `node_finished`, plus iteration and loop variants) alongside `message` chunks → then, by outcome:\n - **Success**: `message_end`, then `workflow_finished`\n - **Failure**: `workflow_finished` with status `failed`, then `error`; no `message_end`\n - **Pause**: `human_input_required`, then `workflow_paused` (the stream ends here; the run resumes separately)\n\n**Add-ons**:\n\n- Text-to-speech auto-play: `tts_message` audio chunks interleave, and `tts_message_end` trails the closing event.\n- Chatflow LLM nodes with `reasoning_format: separated` also emit `reasoning_chunk` deltas carrying the model's reasoning.\n\n**Common fields**: apart from `ping`, every event includes `conversation_id`, `message_id`, and `created_at` (Unix epoch seconds); all but `error` also include `task_id`. Workflow, node, and human-input events (Chatflow apps) nest their payload under `data` and, except for `agent_log`, carry a top-level `workflow_run_id`.\n\n**Reply events**\n\n| Event | App | Fires on | Key fields |\n|:---|:---|:---|:---|\n| `message` | Chatbot, Chatflow, New Agent | each answer chunk (concatenate in order); for New Agent, one closing chunk with the complete answer | `answer` |\n| `agent_message` | Agent, New Agent | each answer chunk (concatenate in order) | `answer` |\n| `agent_thought` | Agent, New Agent | each reasoning or tool-call step | `position`, `thought`, `tool`, `tool_input` (JSON), `observation`, `message_files` |\n| `message_replace` | All | output moderation replaces the answer so far | `answer`; Chatflow also `reason` |\n| `reasoning_chunk` | Chatflow | each reasoning-content delta, when an LLM node uses `reasoning_format: separated` (concatenate in order; a final `is_final: true` event marks reasoning finished and may carry an empty `reasoning`) | `data.message_id`, `data.reasoning`, `data.node_id`, `data.is_final` |\n| `message_file` | Chatbot, Agent | the assistant returns a file | `type`, `belongs_to`, `url` |\n| `message_end` | All | the answer is complete | `metadata` (`usage`, `retriever_resources`) |\n| `tts_message`, `tts_message_end` | Chatbot, Agent, Chatflow | audio chunk / end, when TTS auto-play is on | `audio` |\n\n**Workflow and node events** (Chatflow apps only)\n\nEach event nests its payload under a `data` object.\n\n| Event | Fires on | Key `data` fields |\n|:---|:---|:---|\n| `workflow_started` | the run begins | `inputs` |\n| `node_started` | a node begins | `node_id`, `node_type`, `title` |\n| `node_finished` | a node ends | `status`, `outputs`, `execution_metadata` |\n| `node_retry` | a node retries after a failure | `retry_index` |\n| `iteration_started`, `iteration_next`, `iteration_completed` | Iteration node progress (informational) | `data` |\n| `loop_started`, `loop_next`, `loop_completed` | Loop node progress (informational) | `data` |\n| `agent_log` | an Agent node step log (informational; no `workflow_run_id`) | `data` |\n| `workflow_finished` | the run ends | `status` (`succeeded`, `failed`, `partial-succeeded`, `stopped`), `outputs`, `total_tokens` |\n| `workflow_paused` | the run pauses | `paused_nodes`, `reasons` |\n| `human_input_required` | the run reaches a Human Input node | `form_token`, `form_content`, `expiration_time` |\n\nAfter a pause this stream ends at `workflow_paused`. Submit the form via [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form) or let it time out; the resumed run, including `human_input_form_filled`/`human_input_form_timeout` through `workflow_finished`, streams from [Stream Workflow Events](/en/api-reference/workflow-runs/stream-workflow-events).\n\n**Transport events**\n\n| Event | Fires on | Key fields |\n|:---|:---|:---|\n| `error` | a failure ends the stream; HTTP stays `200` | `status` (e.g. `400`), `code` (e.g. `invalid_param`), `message` |\n| `ping` | keep-alive every 10 seconds | none |"
|
|
},
|
|
"examples": {
|
|
"streamingResponseBasic": {
|
|
"summary": "Response Example - Streaming (Basic)",
|
|
"value": "data: {\"event\": \"message\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"created_at\": 1679586595, \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}"
|
|
},
|
|
"streamingResponseAgent": {
|
|
"summary": "Response Example - Streaming (Agent)",
|
|
"value": "data: {\"event\": \"agent_thought\", \"id\": \"agent_thought_id_1\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"position\": 1, \"thought\": \"Thinking about calling a tool...\", \"tool\": \"dalle3\", \"tool_input\": \"{\\\"dalle3\\\": {\\\"prompt\\\": \\\"a cute cat\\\"}}\", \"created_at\": 1705395332} data: {\"event\": \"message_file\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"created_at\": 1705395332} data: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333} data: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}"
|
|
},
|
|
"streamingResponseWorkflow": {
|
|
"summary": "Response Example - Streaming (Workflow)",
|
|
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"The user greeted me, so\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395335, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}"
|
|
},
|
|
"humanInputPause": {
|
|
"summary": "Response Example - Human Input pause",
|
|
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"paused_nodes\": [\"approval_node\"], \"outputs\": {}, \"reasons\": [{\"TYPE\": \"human_input_required\", \"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"resolved_default_values\": {\"comment\": \"\"}, \"form_token\": \"tok_abc123\", \"expiration_time\": 1705494029}], \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5, \"total_tokens\": 0, \"total_steps\": 1}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `app_unavailable` : App unavailable or misconfigured.\n- `not_chat_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.\n- `bad_request` : Cannot use draft workflow version.\n- `bad_request` : Invalid `workflow_id` format.\n- `bad_request` : `blocking` response mode with a New Agent app.\n- `invalid_param` : The New Agent app has no bound Agent.\n- `agent_not_published` : The bound Agent has no published version. (New Agent apps)\n- `conversation_completed` : The conversation has ended; start a new one by omitting `conversation_id`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"app_unavailable": {
|
|
"summary": "app_unavailable",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "app_unavailable",
|
|
"message": "App unavailable, please check your app configurations."
|
|
}
|
|
},
|
|
"not_chat_app": {
|
|
"summary": "not_chat_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_chat_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"provider_quota_exceeded": {
|
|
"summary": "provider_quota_exceeded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_quota_exceeded",
|
|
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
|
|
}
|
|
},
|
|
"model_currently_not_support": {
|
|
"summary": "model_currently_not_support",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "model_currently_not_support",
|
|
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
|
|
}
|
|
},
|
|
"completion_request_error": {
|
|
"summary": "completion_request_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "completion_request_error",
|
|
"message": "Completion request failed."
|
|
}
|
|
},
|
|
"is_draft_workflow": {
|
|
"summary": "bad_request",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "bad_request",
|
|
"message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. "
|
|
}
|
|
},
|
|
"workflow_id_format_error": {
|
|
"summary": "bad_request",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "bad_request",
|
|
"message": "Invalid workflow_id format: 'not-a-valid-id'. "
|
|
}
|
|
},
|
|
"new_agent_streaming_only": {
|
|
"summary": "bad_request",
|
|
"value": {
|
|
"code": "bad_request",
|
|
"message": "Agent App only supports streaming response mode.",
|
|
"status": 400
|
|
}
|
|
},
|
|
"new_agent_not_bound": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"code": "invalid_param",
|
|
"message": "Agent App has no bound Agent",
|
|
"status": 400
|
|
}
|
|
},
|
|
"new_agent_not_published": {
|
|
"summary": "agent_not_published",
|
|
"value": {
|
|
"code": "agent_not_published",
|
|
"message": "Agent has not been published. Please publish the Agent before using the API.",
|
|
"status": 400
|
|
}
|
|
},
|
|
"conversation_completed": {
|
|
"summary": "conversation_completed",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "conversation_completed",
|
|
"message": "The conversation has ended. Please start a new conversation."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`workflow_version_execution_not_allowed` : A Chatflow request pinned a workflow version via `workflow_id` on the Dify Cloud Sandbox plan.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"workflow_version_execution_not_allowed": {
|
|
"summary": "workflow_version_execution_not_allowed",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "workflow_version_execution_not_allowed",
|
|
"message": "Workflow version execution is not available on your current plan. Please upgrade to a paid plan."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Conversation does not exist.\n- `not_found` : Workflow not found with the specified `workflow_id`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"conversation_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Conversation Not Exists."
|
|
}
|
|
},
|
|
"workflow_not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The workspace's Dify Cloud quota for workflow executions has been exhausted.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"too_many_requests": {
|
|
"summary": "too_many_requests",
|
|
"value": {
|
|
"status": 429,
|
|
"code": "too_many_requests",
|
|
"message": "Too many requests. Please try again later."
|
|
}
|
|
},
|
|
"rate_limit_error": {
|
|
"summary": "rate_limit_error",
|
|
"value": {
|
|
"status": 429,
|
|
"code": "rate_limit_error",
|
|
"message": "Rate Limit Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`internal_server_error` : Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"internal_server_error": {
|
|
"summary": "internal_server_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "internal_server_error",
|
|
"message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chat-messages/send-chat-message",
|
|
"metadata": {
|
|
"title": "Send Chat Message",
|
|
"sidebarTitle": "Send Chat Message"
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl --request POST \\\n --url 'https://{api_base_url}/chat-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"query\": \"What are the specs of the iPhone 13 Pro Max?\", \"inputs\": {}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/chat-messages/{task_id}/stop": {
|
|
"post": {
|
|
"summary": "Stop Chat Message Generation",
|
|
"description": "**Available for**: Chatflow, New Agent, Chatbot, Agent apps.\n\nStops a chat message generation task. Only supported in `streaming` mode.",
|
|
"operationId": "stopChatMessageGeneration",
|
|
"tags": [
|
|
"Chat Messages"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "task_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Task ID, from the streaming events of [Send Chat Message](/en/api-reference/chat-messages/send-chat-message).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"user"
|
|
],
|
|
"properties": {
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. Must match the `user` sent with the original message; if it differs, the stop silently does nothing and still returns success. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"example": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"user": "abc-123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"$ref": "#/components/responses/SuccessResult"
|
|
},
|
|
"400": {
|
|
"description": "- `not_chat_app` : App mode does not match the API route.\n- `invalid_param` : The required `user` field is missing.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_chat_app": {
|
|
"summary": "not_chat_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_chat_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Arg user must be provided."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chat-messages/stop-chat-message-generation",
|
|
"metadata": {
|
|
"title": "Stop Chat Message Generation",
|
|
"sidebarTitle": "Stop Chat Message Generation"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/messages/{message_id}/suggested": {
|
|
"get": {
|
|
"summary": "Get Next Suggested Questions",
|
|
"description": "**Available for**: Chatflow, New Agent, Chatbot, Agent apps.\n\nReturns the follow-up questions suggested for a message.",
|
|
"operationId": "getSuggestedQuestions",
|
|
"tags": [
|
|
"Chat Messages"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "message_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the message to get suggestions for. Get it from a chat response or [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
}
|
|
},
|
|
{
|
|
"name": "user",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully retrieved suggested questions.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SuggestedQuestionsResponse"
|
|
},
|
|
"examples": {
|
|
"suggestedQuestions": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"result": "success",
|
|
"data": [
|
|
"What colors does the iPhone 13 Pro Max come in?",
|
|
"How does the battery compare to iPhone 12?",
|
|
"What is the price range?"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Suggested questions feature is disabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_chat_app": {
|
|
"summary": "not_chat_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_chat_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
},
|
|
"bad_request": {
|
|
"summary": "bad_request",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "bad_request",
|
|
"message": "Suggested Questions Is Disabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Message does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"message_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Message Not Exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`internal_server_error` : Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"internal_server_error": {
|
|
"summary": "internal_server_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "internal_server_error",
|
|
"message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages/{message_id}/suggested?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
|
|
}
|
|
],
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chat-messages/get-next-suggested-questions",
|
|
"metadata": {
|
|
"title": "Get Next Suggested Questions",
|
|
"sidebarTitle": "Get Next Suggested Questions"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/files/upload": {
|
|
"post": {
|
|
"summary": "Upload File",
|
|
"description": "**Available for**: Chatflow, Workflow, New Agent, Chatbot, Agent, Text Generator apps.\n\nUploads a file and returns its `id` for later requests to reference. The file belongs to the uploading end user: only requests carrying the same `user` can reference it.\n\nWhich file types an app actually consumes depends on its file-upload settings; read them from [Get App Parameters](/en/api-reference/applications/get-app-parameters).",
|
|
"operationId": "uploadChatFile",
|
|
"tags": [
|
|
"Files"
|
|
],
|
|
"requestBody": {
|
|
"description": "File upload request. Requires multipart/form-data.",
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"file"
|
|
],
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "The file to upload, as one `multipart/form-data` part. The filename must not contain `/` or `\\`.\n\nAny extension is accepted unless it is on the deployment's security blacklist (`UPLOAD_FILE_EXTENSION_BLACKLIST`, empty by default).\n\nSize limits per category: images 10 MB, audio 50 MB, video 100 MB, other files 15 MB by default (Dify Cloud uses the defaults). Self-hosted deployments adjust them with the `UPLOAD_*_FILE_SIZE_LIMIT` [environment variables](/en/self-host/deploy/configuration/environments)."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier this upload belongs to, defined by your app and unique within it. Omit it to attribute the upload to the shared `DEFAULT-USER`. Only later requests with the same `user` can reference the file. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "File uploaded successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/FileUploadResponse"
|
|
},
|
|
"examples": {
|
|
"uploadSuccess": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"reference": null,
|
|
"name": "product-photo.png",
|
|
"size": 204800,
|
|
"extension": "png",
|
|
"mime_type": "image/png",
|
|
"created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
|
|
"created_at": 1705407629,
|
|
"preview_url": null,
|
|
"source_url": "https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI=",
|
|
"original_url": null,
|
|
"user_id": null,
|
|
"tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
|
|
"conversation_id": null,
|
|
"file_key": null
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `invalid_param` : The filename contains `/` or `\\`, or the file's extension is on the deployment's blacklist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"no_file_uploaded": {
|
|
"summary": "no_file_uploaded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "no_file_uploaded",
|
|
"message": "Please upload your file."
|
|
}
|
|
},
|
|
"too_many_files": {
|
|
"summary": "too_many_files",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "too_many_files",
|
|
"message": "Only one file is allowed."
|
|
}
|
|
},
|
|
"filename_not_exists_error": {
|
|
"summary": "filename_not_exists_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "filename_not_exists_error",
|
|
"message": "The specified filename does not exist."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "File extension '.exe' is not allowed for security reasons"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"413": {
|
|
"description": "`file_too_large` : The file exceeds its category's size limit (see the `file` field). The runtime `message` is currently returned as an empty string (a known backend quirk); rely on the `code` and status.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"file_too_large": {
|
|
"summary": "file_too_large",
|
|
"value": {
|
|
"status": 413,
|
|
"code": "file_too_large",
|
|
"message": ""
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"415": {
|
|
"description": "`unsupported_file_type` : The uploaded `file` part declares no MIME type.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"unsupported_file_type": {
|
|
"summary": "unsupported_file_type",
|
|
"value": {
|
|
"status": 415,
|
|
"code": "unsupported_file_type",
|
|
"message": "File type not allowed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/files/upload-file",
|
|
"metadata": {
|
|
"title": "Upload File",
|
|
"sidebarTitle": "Upload File"
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl --request POST \\\n --url 'https://{api_base_url}/files/upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@product-photo.png' \\\n --form 'user={user}'"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/files/{file_id}/preview": {
|
|
"get": {
|
|
"summary": "Download File",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent, Text Generator apps.\n\nReturns the raw bytes of a file previously returned by [Upload File](/en/api-reference/files/upload-file). A file is reachable only through the app whose messages reference it.",
|
|
"operationId": "previewChatFile",
|
|
"tags": [
|
|
"Files"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "file_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the file to download, from the Upload File response.",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
}
|
|
},
|
|
{
|
|
"name": "as_attachment",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "When `true`, the file downloads as an attachment instead of rendering inline in the browser.",
|
|
"schema": {
|
|
"type": "boolean",
|
|
"default": false
|
|
}
|
|
},
|
|
{
|
|
"name": "user",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "End-user identifier, defined by your app and unique within it. It has no effect on file access here, which is scoped by app and message rather than by `user`. See [End User Identity](/en/api-reference/guides/end-user-identity).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.",
|
|
"content": {
|
|
"application/octet-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "binary"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`file_access_denied` : The file exists but belongs to a different app or workspace.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"file_access_denied": {
|
|
"summary": "file_access_denied",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "file_access_denied",
|
|
"message": "Access to the requested file is denied."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`file_not_found` : No file with this ID is reachable through this app's messages.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"file_not_found": {
|
|
"summary": "file_not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "file_not_found",
|
|
"message": "The requested file was not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/files/download-file",
|
|
"metadata": {
|
|
"title": "Download File",
|
|
"sidebarTitle": "Download File"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/end-users/{end_user_id}": {
|
|
"get": {
|
|
"summary": "Get End User Info",
|
|
"description": "**Available for**: Chatflow, Workflow, New Agent, Chatbot, Agent, Text Generator apps.\n\nReturns an end user's details by ID. Useful for resolving an end-user ID returned by another endpoint, such as `created_by` in the [Upload File](/en/api-reference/files/upload-file) response.",
|
|
"operationId": "getEndUserChat",
|
|
"tags": [
|
|
"End Users"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "end_user_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the end user to look up.",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "End user retrieved successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/EndUserDetail"
|
|
},
|
|
"examples": {
|
|
"endUserDetail": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
|
|
"tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
|
|
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"type": "service-api",
|
|
"external_user_id": "abc-123",
|
|
"name": null,
|
|
"is_anonymous": false,
|
|
"session_id": "abc-123",
|
|
"created_at": "2024-01-16T12:00:29Z",
|
|
"updated_at": "2024-01-16T12:00:29Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`end_user_not_found` : End user not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"end_user_not_found": {
|
|
"summary": "end_user_not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "end_user_not_found",
|
|
"message": "End user not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/end-users/get-end-user-info",
|
|
"metadata": {
|
|
"title": "Get End User Info",
|
|
"sidebarTitle": "Get End User Info"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/messages/{message_id}/feedbacks": {
|
|
"post": {
|
|
"summary": "Submit Message Feedback",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent, Text Generator apps.\n\nRecords a `like` or `dislike` rating, plus an optional comment, on a message. Submitting `null` for `rating` revokes the message's existing feedback.",
|
|
"operationId": "postChatMessageFeedback",
|
|
"tags": [
|
|
"Feedback"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "message_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the message to give feedback on. Get message IDs from [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MessageFeedbackRequest"
|
|
},
|
|
"examples": {
|
|
"likeFeedback": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"rating": "like",
|
|
"user": "abc-123",
|
|
"content": "This answer was very helpful!"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"$ref": "#/components/responses/SuccessResult"
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The required `user` field is omitted, or `rating` is `null` but there is no existing feedback to revoke.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Arg user must be provided."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Message does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"message_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Message Not Exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/feedback/submit-message-feedback",
|
|
"metadata": {
|
|
"title": "Submit Message Feedback",
|
|
"sidebarTitle": "Submit Message Feedback"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/app/feedbacks": {
|
|
"get": {
|
|
"summary": "List App Feedbacks",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent, Text Generator apps.\n\nReturns a paginated list of all feedback on the app's messages, including both end-user and admin submissions.",
|
|
"operationId": "getChatAppFeedbacks",
|
|
"tags": [
|
|
"Feedback"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "page",
|
|
"in": "query",
|
|
"description": "Page number.",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 1,
|
|
"minimum": 1
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Feedback items per page.",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20,
|
|
"minimum": 1,
|
|
"maximum": 101
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "A list of application feedbacks.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AppFeedbacksResponse"
|
|
},
|
|
"examples": {
|
|
"feedbacksList": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456",
|
|
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
|
|
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
|
|
"rating": "like",
|
|
"content": "The response accurately answered my question about product specifications.",
|
|
"from_source": "user",
|
|
"from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
|
|
"from_account_id": null,
|
|
"created_at": "2025-01-16T14:30:29Z",
|
|
"updated_at": "2025-01-16T14:30:29Z"
|
|
},
|
|
{
|
|
"id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678",
|
|
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603",
|
|
"message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1",
|
|
"rating": "dislike",
|
|
"content": "The answer was too vague and did not address the specific pricing question.",
|
|
"from_source": "user",
|
|
"from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210",
|
|
"from_account_id": null,
|
|
"created_at": "2025-01-15T09:12:45Z",
|
|
"updated_at": "2025-01-15T09:12:45Z"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/feedback/list-app-feedbacks",
|
|
"metadata": {
|
|
"title": "List App Feedbacks",
|
|
"sidebarTitle": "List App Feedbacks"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/conversations": {
|
|
"get": {
|
|
"summary": "List Conversations",
|
|
"description": "**Available for**: Chatflow, New Agent, Chatbot, Agent apps.\n\nLists an end user's conversations, most recently active first.",
|
|
"operationId": "getConversationsList",
|
|
"tags": [
|
|
"Conversations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "user",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "last_id",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Pagination cursor: the `id` of the last conversation on the current page. Omit to fetch the first page.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Number of records to return.",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20,
|
|
"minimum": 1,
|
|
"maximum": 100
|
|
}
|
|
},
|
|
{
|
|
"name": "sort_by",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Field to sort by. Prefix with `-` for descending order.",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"created_at",
|
|
"-created_at",
|
|
"updated_at",
|
|
"-updated_at"
|
|
],
|
|
"default": "-updated_at"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully retrieved conversations list.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConversationsListResponse"
|
|
},
|
|
"examples": {
|
|
"conversationsList": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"limit": 20,
|
|
"has_more": false,
|
|
"data": [
|
|
{
|
|
"id": "45701982-8118-4bc5-8e9b-64562b4555f2",
|
|
"name": "iPhone Specs Chat",
|
|
"inputs": {
|
|
"city": "San Francisco"
|
|
},
|
|
"status": "normal",
|
|
"introduction": "Welcome! How can I help you today?",
|
|
"created_at": 1705407629,
|
|
"updated_at": 1705411229
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`not_chat_app` : App mode does not match the API route.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_chat_app": {
|
|
"summary": "not_chat_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_chat_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Last conversation does not exist (invalid `last_id`).",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"last_conversation_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Last Conversation Not Exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/conversations/list-conversations",
|
|
"metadata": {
|
|
"title": "List Conversations",
|
|
"sidebarTitle": "List Conversations"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/messages": {
|
|
"get": {
|
|
"summary": "List Conversation Messages",
|
|
"description": "**Available for**: Chatflow, New Agent, Chatbot, Agent apps.\n\nReturns a conversation's message history, newest first. Pass `first_id` to page backward into older messages.",
|
|
"operationId": "getConversationHistory",
|
|
"tags": [
|
|
"Conversations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "conversation_id",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "ID of the conversation to read. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "user",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "first_id",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Pagination cursor: the `id` of the first message on the current page. Pass it to fetch the previous (older) page; omit to fetch the latest messages.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Number of chat history messages to return per request.",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20,
|
|
"minimum": 1,
|
|
"maximum": 100
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully retrieved conversation history.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConversationHistoryResponse"
|
|
},
|
|
"examples": {
|
|
"conversationHistory": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"limit": 20,
|
|
"has_more": false,
|
|
"data": [
|
|
{
|
|
"id": "9da23599-e713-473b-982c-4328d4f5c78a",
|
|
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
|
|
"parent_message_id": null,
|
|
"inputs": {
|
|
"city": "San Francisco"
|
|
},
|
|
"query": "What are the specs of the iPhone 13 Pro Max?",
|
|
"answer": "iPhone 13 Pro Max specs are listed here:...",
|
|
"status": "normal",
|
|
"error": null,
|
|
"message_files": [],
|
|
"feedback": {
|
|
"rating": "like"
|
|
},
|
|
"retriever_resources": [],
|
|
"agent_thoughts": [],
|
|
"created_at": 1705407629,
|
|
"extra_contents": [],
|
|
"message_tokens": 100,
|
|
"answer_tokens": 58,
|
|
"total_tokens": 158,
|
|
"provider_response_latency": 1.234,
|
|
"total_price": "0.0012825",
|
|
"currency": "USD"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`not_chat_app` : App mode does not match the API route.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_chat_app": {
|
|
"summary": "not_chat_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_chat_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Conversation does not exist.\n- `not_found` : First message does not exist (invalid `first_id`).",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"conversation_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Conversation Not Exists."
|
|
}
|
|
},
|
|
"first_message_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "First Message Not Exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages?conversation_id={conversation_id}&user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
|
|
}
|
|
],
|
|
"x-mint": {
|
|
"href": "/en/api-reference/conversations/list-conversation-messages",
|
|
"metadata": {
|
|
"title": "List Conversation Messages",
|
|
"sidebarTitle": "List Conversation Messages"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/conversations/{conversation_id}/variables": {
|
|
"get": {
|
|
"summary": "List Conversation Variables",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent apps.\n\nLists the variables stored in a conversation.",
|
|
"operationId": "getConversationVariables",
|
|
"tags": [
|
|
"Conversations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "conversation_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the conversation whose variables to list. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "user",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "last_id",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Pagination cursor: the `id` of the last variable on the current page. Omit to fetch the first page.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Number of records to return.",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20,
|
|
"minimum": 1,
|
|
"maximum": 100
|
|
}
|
|
},
|
|
{
|
|
"name": "variable_name",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Filter variables by a specific name.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"maxLength": 255
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully retrieved conversation variables.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConversationVariablesResponse"
|
|
},
|
|
"examples": {
|
|
"conversationVariables": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"limit": 20,
|
|
"has_more": false,
|
|
"data": [
|
|
{
|
|
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"name": "user_preference",
|
|
"value_type": "string",
|
|
"value": "dark_mode",
|
|
"description": "User preference setting",
|
|
"created_at": 1705407629,
|
|
"updated_at": 1705411229
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `not_chat_app` : App mode does not match the API route.\n- `invalid_param` : The `last_id` does not match any variable in this conversation.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_chat_app": {
|
|
"summary": "not_chat_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_chat_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
},
|
|
"invalid_last_id": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": ""
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Conversation does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"conversation_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Conversation Not Exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/conversations/list-conversation-variables",
|
|
"metadata": {
|
|
"title": "List Conversation Variables",
|
|
"sidebarTitle": "List Conversation Variables"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/conversations/{conversation_id}/name": {
|
|
"post": {
|
|
"summary": "Rename Conversation",
|
|
"description": "**Available for**: Chatflow, New Agent, Chatbot, Agent apps.\n\nRenames a conversation, or auto-generates a name from its messages when `auto_generate` is `true`. The name is what clients display in a multi-conversation list.",
|
|
"operationId": "renameConversation",
|
|
"tags": [
|
|
"Conversations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "conversation_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the conversation to rename. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConversationRenameRequest"
|
|
},
|
|
"examples": {
|
|
"renameExample": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"name": "iPhone Specs Chat",
|
|
"user": "abc-123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Conversation renamed successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConversationListItem"
|
|
},
|
|
"examples": {
|
|
"renamedConversation": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "45701982-8118-4bc5-8e9b-64562b4555f2",
|
|
"name": "iPhone Specs Chat",
|
|
"inputs": {
|
|
"city": "San Francisco"
|
|
},
|
|
"status": "normal",
|
|
"introduction": "Welcome! How can I help you today?",
|
|
"created_at": 1705407629,
|
|
"updated_at": 1705411229
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `not_chat_app` : App mode does not match the API route.\n- `invalid_param` : `auto_generate` is `true` but the conversation has no messages to generate a name from.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_chat_app": {
|
|
"summary": "not_chat_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_chat_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
},
|
|
"no_messages": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": ""
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Conversation does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"conversation_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Conversation Not Exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/conversations/rename-conversation",
|
|
"metadata": {
|
|
"title": "Rename Conversation",
|
|
"sidebarTitle": "Rename Conversation"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/conversations/{conversation_id}/variables/{variable_id}": {
|
|
"put": {
|
|
"summary": "Update Conversation Variable",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent apps.\n\nUpdates a conversation variable's value. The new value must match the variable's existing type.",
|
|
"operationId": "updateChatConversationVariable",
|
|
"tags": [
|
|
"Conversations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "conversation_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the conversation that owns the variable. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
}
|
|
},
|
|
{
|
|
"name": "variable_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the variable to update. Get variable IDs from [List Conversation Variables](/en/api-reference/conversations/list-conversation-variables).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConversationVariableUpdateRequest"
|
|
},
|
|
"examples": {
|
|
"updateStringVariable": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"value": "new value",
|
|
"user": "abc-123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Variable updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConversationVariableItem"
|
|
},
|
|
"examples": {
|
|
"updatedVariable": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"name": "user_preference",
|
|
"value_type": "string",
|
|
"value": "new value",
|
|
"description": "User preference setting",
|
|
"created_at": 1705407629,
|
|
"updated_at": 1705411229
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Variable value type mismatch.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_chat_app": {
|
|
"summary": "not_chat_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_chat_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
},
|
|
"type_mismatch": {
|
|
"summary": "bad_request",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "bad_request",
|
|
"message": "Type mismatch: variable 'user_preference' expects string, but got number type"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Conversation does not exist.\n- `not_found` : Conversation variable does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"conversation_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Conversation Not Exists."
|
|
}
|
|
},
|
|
"variable_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Conversation Variable Not Exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/conversations/update-conversation-variable",
|
|
"metadata": {
|
|
"title": "Update Conversation Variable",
|
|
"sidebarTitle": "Update Conversation Variable"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/conversations/{conversation_id}": {
|
|
"delete": {
|
|
"summary": "Delete Conversation",
|
|
"description": "**Available for**: Chatflow, New Agent, Chatbot, Agent apps.\n\nDeletes a conversation.",
|
|
"operationId": "deleteConversation",
|
|
"tags": [
|
|
"Conversations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "conversation_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the conversation to delete. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"description": "A JSON body is always required, even when `user` is omitted; send `{}` in that case.",
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"deleteExample": {
|
|
"value": {
|
|
"user": "abc-123"
|
|
},
|
|
"summary": "Request Example"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"204": {
|
|
"description": "Conversation deleted successfully. No content returned."
|
|
},
|
|
"400": {
|
|
"description": "`not_chat_app` : App mode does not match the API route.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_chat_app": {
|
|
"summary": "not_chat_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_chat_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Conversation does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"conversation_not_exists": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Conversation Not Exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/conversations/delete-conversation",
|
|
"metadata": {
|
|
"title": "Delete Conversation",
|
|
"sidebarTitle": "Delete Conversation"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/audio-to-text": {
|
|
"post": {
|
|
"summary": "Convert Audio to Text",
|
|
"description": "**Available for**: Chatflow, Workflow, New Agent, Chatbot, Agent, Text Generator apps.\n\nTranscribes an uploaded audio file to text using the app's configured speech-to-text model.",
|
|
"operationId": "audioToText",
|
|
"tags": [
|
|
"Audio"
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AudioToTextRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully converted audio to text.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AudioToTextResponse"
|
|
},
|
|
"examples": {
|
|
"audioToTextSuccess": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"text": "Hello, I would like to know more about the iPhone 13 Pro Max."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `app_unavailable` : The app is unavailable or misconfigured.\n- `speech_to_text_disabled` : Speech-to-text is disabled for this app.\n- `provider_not_support_speech_to_text` : The model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials are configured.\n- `provider_quota_exceeded` : The model provider quota is exhausted.\n- `model_currently_not_support` : The current model does not support this operation.\n- `completion_request_error` : The speech recognition request failed.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"app_unavailable": {
|
|
"summary": "app_unavailable",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "app_unavailable",
|
|
"message": "App unavailable, please check your app configurations."
|
|
}
|
|
},
|
|
"speech_to_text_disabled": {
|
|
"summary": "speech_to_text_disabled",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "speech_to_text_disabled",
|
|
"message": "Speech to text is disabled."
|
|
}
|
|
},
|
|
"provider_not_support_speech_to_text": {
|
|
"summary": "provider_not_support_speech_to_text",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_support_speech_to_text",
|
|
"message": "Provider not support speech to text."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"provider_quota_exceeded": {
|
|
"summary": "provider_quota_exceeded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_quota_exceeded",
|
|
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
|
|
}
|
|
},
|
|
"model_currently_not_support": {
|
|
"summary": "model_currently_not_support",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "model_currently_not_support",
|
|
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
|
|
}
|
|
},
|
|
"completion_request_error": {
|
|
"summary": "completion_request_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "completion_request_error",
|
|
"message": "Completion request failed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"413": {
|
|
"description": "`audio_too_large` : The audio file exceeds the `30 MB` size limit.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"audio_too_large": {
|
|
"summary": "audio_too_large",
|
|
"value": {
|
|
"status": 413,
|
|
"code": "audio_too_large",
|
|
"message": "Audio size larger than 30 mb"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"415": {
|
|
"description": "`unsupported_audio_type` : The file's MIME type is not one of the accepted audio types (see the `file` field).",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"unsupported_audio_type": {
|
|
"summary": "unsupported_audio_type",
|
|
"value": {
|
|
"status": 415,
|
|
"code": "unsupported_audio_type",
|
|
"message": "Audio type not allowed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`internal_server_error` : Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"internal_server_error": {
|
|
"summary": "internal_server_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "internal_server_error",
|
|
"message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/audio/convert-audio-to-text",
|
|
"metadata": {
|
|
"title": "Convert Audio to Text",
|
|
"sidebarTitle": "Convert Audio to Text"
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl --request POST \\\n --url 'https://{api_base_url}/audio-to-text' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@meeting-question.mp3' \\\n --form 'user={user}'"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/text-to-audio": {
|
|
"post": {
|
|
"summary": "Convert Text to Audio",
|
|
"description": "**Available for**: Chatflow, Workflow, New Agent, Chatbot, Agent, Text Generator apps.\n\nConverts text to speech audio. Pass `text` to synthesize arbitrary text, or `message_id` to voice an existing message's answer.",
|
|
"operationId": "textToAudioChat",
|
|
"tags": [
|
|
"Audio"
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/TextToAudioRequest"
|
|
},
|
|
"examples": {
|
|
"textToAudioExample": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"text": "Hello, welcome to our service.",
|
|
"user": "abc-123",
|
|
"voice": "alloy",
|
|
"streaming": false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). When the configured TTS provider returns a stream, the audio is delivered as `audio/mpeg` with chunked transfer encoding; the request `streaming` field does not control this.",
|
|
"content": {
|
|
"audio/mpeg": {
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "binary"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `app_unavailable` : The app is unavailable or misconfigured.\n- `invalid_param` : Text-to-speech is not enabled, `text` is missing, or no voice is available.\n- `provider_not_initialize` : No valid model provider credentials are configured.\n- `provider_quota_exceeded` : The model provider quota is exhausted.\n- `model_currently_not_support` : The current model does not support this operation.\n- `completion_request_error` : The text-to-speech request failed.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"app_unavailable": {
|
|
"summary": "app_unavailable",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "app_unavailable",
|
|
"message": "App unavailable, please check your app configurations."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "TTS is not enabled"
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"provider_quota_exceeded": {
|
|
"summary": "provider_quota_exceeded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_quota_exceeded",
|
|
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
|
|
}
|
|
},
|
|
"model_currently_not_support": {
|
|
"summary": "model_currently_not_support",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "model_currently_not_support",
|
|
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
|
|
}
|
|
},
|
|
"completion_request_error": {
|
|
"summary": "completion_request_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "completion_request_error",
|
|
"message": "Completion request failed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`internal_server_error` : Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"internal_server_error": {
|
|
"summary": "internal_server_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "internal_server_error",
|
|
"message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/audio/convert-text-to-audio",
|
|
"metadata": {
|
|
"title": "Convert Text to Audio",
|
|
"sidebarTitle": "Convert Text to Audio"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/info": {
|
|
"get": {
|
|
"summary": "Get App Info",
|
|
"description": "**Available for**: Chatflow, Workflow, New Agent, Chatbot, Agent, Text Generator apps.\n\nReturns basic information about the app: name, description, tags, mode, and author.",
|
|
"operationId": "getChatAppInfo",
|
|
"tags": [
|
|
"Applications"
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Basic information of the application.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AppInfoResponse"
|
|
},
|
|
"examples": {
|
|
"appInfo": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"name": "My Chat App",
|
|
"description": "A helpful customer service chatbot.",
|
|
"tags": [
|
|
"customer-service",
|
|
"chatbot"
|
|
],
|
|
"mode": "chat",
|
|
"author_name": "Dify Team"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/applications/get-app-info",
|
|
"metadata": {
|
|
"title": "Get App Info",
|
|
"sidebarTitle": "Get App Info"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/parameters": {
|
|
"get": {
|
|
"summary": "Get App Parameters",
|
|
"description": "**Available for**: Chatflow, Workflow, New Agent, Chatbot, Agent, Text Generator apps.\n\nReturns the app's front-end configuration: the opening statement and suggested questions, feature toggles, the user input form, and file-upload limits. Use it to render the app's inputs and apply the correct upload limits.",
|
|
"operationId": "getChatAppParameters",
|
|
"tags": [
|
|
"Applications"
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Application parameters information.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AppParametersResponse"
|
|
},
|
|
"examples": {
|
|
"appParameters": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"opening_statement": "Hello! How can I help you today?",
|
|
"suggested_questions": [
|
|
"What can you do?",
|
|
"Tell me about your features."
|
|
],
|
|
"suggested_questions_after_answer": {
|
|
"enabled": true
|
|
},
|
|
"speech_to_text": {
|
|
"enabled": false
|
|
},
|
|
"text_to_speech": {
|
|
"enabled": false,
|
|
"voice": "alloy",
|
|
"language": "en-US",
|
|
"autoPlay": "disabled"
|
|
},
|
|
"retriever_resource": {
|
|
"enabled": true
|
|
},
|
|
"annotation_reply": {
|
|
"enabled": false
|
|
},
|
|
"more_like_this": {
|
|
"enabled": false
|
|
},
|
|
"sensitive_word_avoidance": {
|
|
"enabled": false
|
|
},
|
|
"user_input_form": [
|
|
{
|
|
"text-input": {
|
|
"label": "City",
|
|
"variable": "city",
|
|
"required": true,
|
|
"default": ""
|
|
}
|
|
}
|
|
],
|
|
"file_upload": {
|
|
"image": {
|
|
"enabled": true,
|
|
"number_limits": 3,
|
|
"detail": "high",
|
|
"transfer_methods": [
|
|
"remote_url",
|
|
"local_file"
|
|
]
|
|
}
|
|
},
|
|
"system_parameters": {
|
|
"file_size_limit": 15,
|
|
"image_file_size_limit": 10,
|
|
"audio_file_size_limit": 50,
|
|
"video_file_size_limit": 100,
|
|
"workflow_file_upload_limit": 10
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `app_unavailable` : The app is unavailable or misconfigured.\n- `agent_not_published` : The app's Agent has no published version yet. (New Agent apps)",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"app_unavailable": {
|
|
"summary": "app_unavailable",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "app_unavailable",
|
|
"message": "App unavailable, please check your app configurations."
|
|
}
|
|
},
|
|
"agent_not_published": {
|
|
"summary": "agent_not_published",
|
|
"value": {
|
|
"code": "agent_not_published",
|
|
"message": "Agent has not been published. Please publish the Agent before using the API.",
|
|
"status": 400
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/applications/get-app-parameters",
|
|
"metadata": {
|
|
"title": "Get App Parameters",
|
|
"sidebarTitle": "Get App Parameters"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/meta": {
|
|
"get": {
|
|
"summary": "Get App Meta",
|
|
"description": "**Available for**: Chatflow, Workflow, New Agent, Chatbot, Agent, Text Generator apps.\n\nReturns the display icons for the tools this app uses, keyed by tool name.",
|
|
"operationId": "getChatAppMeta",
|
|
"tags": [
|
|
"Applications"
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully retrieved application meta information.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AppMetaResponse"
|
|
},
|
|
"examples": {
|
|
"appMeta": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"tool_icons": {
|
|
"dalle3": "https://example.com/icons/dalle3.png",
|
|
"calculator": {
|
|
"background": "#4A90D9",
|
|
"content": "🧮"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/applications/get-app-meta",
|
|
"metadata": {
|
|
"title": "Get App Meta",
|
|
"sidebarTitle": "Get App Meta"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/site": {
|
|
"get": {
|
|
"summary": "Get App WebApp Settings",
|
|
"description": "**Available for**: Chatflow, Workflow, New Agent, Chatbot, Agent, Text Generator apps.\n\nReturns the branding and display settings for the app's hosted WebApp, such as its title, icon, theme colors, and default language.",
|
|
"operationId": "getChatWebAppSettings",
|
|
"tags": [
|
|
"Applications"
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "WebApp settings of the application.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WebAppSettingsResponse"
|
|
},
|
|
"examples": {
|
|
"webAppSettings": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"title": "My Chat App",
|
|
"chat_color_theme": "#4A90D9",
|
|
"chat_color_theme_inverted": false,
|
|
"icon_type": "emoji",
|
|
"icon": "🤖",
|
|
"icon_background": "#FFFFFF",
|
|
"icon_url": null,
|
|
"description": "A helpful customer service chatbot.",
|
|
"copyright": "2025 Dify",
|
|
"privacy_policy": "https://example.com/privacy",
|
|
"input_placeholder": "Ask me anything about our products...",
|
|
"custom_disclaimer": "",
|
|
"default_language": "en-US",
|
|
"show_workflow_steps": false,
|
|
"use_icon_as_answer_icon": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Site not found for this application or the workspace has been archived.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "You don't have the permission to access the requested resource. It is either read-protected or not readable by the server."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/applications/get-app-webapp-settings",
|
|
"metadata": {
|
|
"title": "Get App WebApp Settings",
|
|
"sidebarTitle": "Get App WebApp Settings"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/apps/annotations": {
|
|
"post": {
|
|
"summary": "Create Annotation",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent apps.\n\nCreates an annotation. Annotations are predefined question-answer pairs the app returns directly on a match, instead of generating a fresh response.",
|
|
"operationId": "createAnnotation",
|
|
"tags": [
|
|
"Annotations"
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateAnnotationRequest"
|
|
},
|
|
"examples": {
|
|
"createAnnotation": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"question": "What is Dify?",
|
|
"answer": "Dify is an open-source LLM application development platform."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Annotation created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnnotationItem"
|
|
},
|
|
"examples": {
|
|
"createdAnnotation": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"question": "What is Dify?",
|
|
"answer": "Dify is an open-source LLM application development platform.",
|
|
"hit_count": 0,
|
|
"created_at": 1705407629
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/annotations/create-annotation",
|
|
"metadata": {
|
|
"title": "Create Annotation",
|
|
"sidebarTitle": "Create Annotation"
|
|
}
|
|
}
|
|
},
|
|
"get": {
|
|
"summary": "List Annotations",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent apps.\n\nLists the app's annotations, optionally filtered by keyword.",
|
|
"operationId": "getAnnotationList",
|
|
"tags": [
|
|
"Annotations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "page",
|
|
"in": "query",
|
|
"description": "Page number.",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 1,
|
|
"minimum": 1
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Number of items per page. Requests above 100 are capped at 100.",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20,
|
|
"minimum": 1
|
|
}
|
|
},
|
|
{
|
|
"name": "keyword",
|
|
"in": "query",
|
|
"description": "Keyword to filter annotations by question or answer content.",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully retrieved annotation list.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnnotationListResponse"
|
|
},
|
|
"examples": {
|
|
"annotationList": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"question": "What is Dify?",
|
|
"answer": "Dify is an open-source LLM application development platform.",
|
|
"hit_count": 5,
|
|
"created_at": 1705407629
|
|
}
|
|
],
|
|
"has_more": false,
|
|
"limit": 20,
|
|
"total": 1,
|
|
"page": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/annotations/list-annotations",
|
|
"metadata": {
|
|
"title": "List Annotations",
|
|
"sidebarTitle": "List Annotations"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/apps/annotations/{annotation_id}": {
|
|
"put": {
|
|
"summary": "Update Annotation",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent apps.\n\nUpdates an annotation's question and answer.",
|
|
"operationId": "updateAnnotation",
|
|
"tags": [
|
|
"Annotations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "annotation_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the annotation to update. Get annotation IDs from [List Annotations](/en/api-reference/annotations/list-annotations).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/UpdateAnnotationRequest"
|
|
},
|
|
"examples": {
|
|
"updateAnnotation": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"question": "What is Dify?",
|
|
"answer": "Dify is an open-source LLM application development platform for building AI-powered apps."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Annotation updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnnotationItem"
|
|
},
|
|
"examples": {
|
|
"updatedAnnotation": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"question": "What is Dify?",
|
|
"answer": "Dify is an open-source LLM application development platform for building AI-powered apps.",
|
|
"hit_count": 5,
|
|
"created_at": 1705407629
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Annotation does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Annotation not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/annotations/update-annotation",
|
|
"metadata": {
|
|
"title": "Update Annotation",
|
|
"sidebarTitle": "Update Annotation"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"summary": "Delete Annotation",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent apps.\n\nDeletes an annotation and its associated hit history.",
|
|
"operationId": "deleteAnnotation",
|
|
"tags": [
|
|
"Annotations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "annotation_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "ID of the annotation to delete. Get annotation IDs from [List Annotations](/en/api-reference/annotations/list-annotations).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "Annotation deleted successfully."
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Annotation does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Annotation not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/annotations/delete-annotation",
|
|
"metadata": {
|
|
"title": "Delete Annotation",
|
|
"sidebarTitle": "Delete Annotation"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/apps/annotation-reply/{action}": {
|
|
"post": {
|
|
"summary": "Configure Annotation Reply",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent apps.\n\nEnables or disables annotation reply for the app. Runs asynchronously; track progress with [Get Annotation Reply Job Status](/en/api-reference/annotations/get-annotation-reply-job-status).\n\nThe body is validated before the action runs, so `score_threshold`, `embedding_provider_name`, and `embedding_model_name` are required even for `disable`.",
|
|
"operationId": "initialAnnotationReplySettings",
|
|
"tags": [
|
|
"Annotations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "action",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Whether to enable or disable annotation reply.",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"enable",
|
|
"disable"
|
|
]
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest"
|
|
},
|
|
"examples": {
|
|
"enableAnnotationReply": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"score_threshold": 0.9,
|
|
"embedding_provider_name": "openai",
|
|
"embedding_model_name": "text-embedding-3-small"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Annotation reply settings task initiated.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse"
|
|
},
|
|
"examples": {
|
|
"annotationReplyResponse": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"job_status": "waiting"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/annotations/configure-annotation-reply",
|
|
"metadata": {
|
|
"title": "Configure Annotation Reply",
|
|
"sidebarTitle": "Configure Annotation Reply"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/apps/annotation-reply/{action}/status/{job_id}": {
|
|
"get": {
|
|
"summary": "Get Annotation Reply Job Status",
|
|
"description": "**Available for**: Chatflow, Chatbot, Agent apps.\n\nReturns the status of an annotation reply configuration job started by [Configure Annotation Reply](/en/api-reference/annotations/configure-annotation-reply).",
|
|
"operationId": "getInitialAnnotationReplySettingsStatus",
|
|
"tags": [
|
|
"Annotations"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "action",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Action type, must match the [Configure Annotation Reply](/en/api-reference/annotations/configure-annotation-reply) call.",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"enable",
|
|
"disable"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"name": "job_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Job ID returned by [Configure Annotation Reply](/en/api-reference/annotations/configure-annotation-reply).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully retrieved task status.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse"
|
|
},
|
|
"examples": {
|
|
"jobStatus": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"job_status": "completed",
|
|
"error_msg": ""
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The specified job does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "The job does not exist."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/annotations/get-annotation-reply-job-status",
|
|
"metadata": {
|
|
"title": "Get Annotation Reply Job Status",
|
|
"sidebarTitle": "Get Annotation Reply Job Status"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workflows/run/{workflow_run_id}": {
|
|
"get": {
|
|
"summary": "Get Workflow Run Detail",
|
|
"description": "**Available for**: Chatflow, Workflow apps.\n\nGet a single workflow run's status, inputs, outputs, and execution metrics.",
|
|
"operationId": "getWorkflowRunDetail",
|
|
"tags": [
|
|
"Workflow Runs"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "workflow_run_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Workflow run ID, from the response or streaming events of [Run Workflow](/en/api-reference/workflow-runs/run-workflow), or from message metadata in Chatflow apps.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully retrieved workflow run details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkflowRunDetailResponse"
|
|
},
|
|
"examples": {
|
|
"workflowRunDetail": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
|
|
"workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345",
|
|
"status": "succeeded",
|
|
"inputs": "{\"query\": \"Translate this to French\"}",
|
|
"outputs": {
|
|
"result": "Traduisez ceci en francais"
|
|
},
|
|
"error": null,
|
|
"total_steps": 3,
|
|
"total_tokens": 150,
|
|
"created_at": 1705407629,
|
|
"finished_at": 1705407630,
|
|
"elapsed_time": 1.23
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`not_workflow_app` : App mode does not match the API route.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_workflow_app": {
|
|
"summary": "not_workflow_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_workflow_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Workflow run not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"workflow_run_not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Workflow run not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/workflow-runs/get-workflow-run-detail",
|
|
"metadata": {
|
|
"title": "Get Workflow Run Detail",
|
|
"sidebarTitle": "Get Workflow Run Detail"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workflows/logs": {
|
|
"get": {
|
|
"summary": "List Workflow Logs",
|
|
"description": "**Available for**: Chatflow, Workflow apps.\n\nList past workflow runs with optional filters. Each entry is a run-level summary (status, token usage, step count, and timing), not a node-by-node execution log.\n\nTo follow a run's node-level events, stream it instead:\n\n- **A run you start**: use [Run Workflow](/en/api-reference/workflow-runs/run-workflow) in streaming mode, which emits `node_started` and `node_finished` as the run executes.\n- **A run already in progress**: call [Stream Workflow Events](/en/api-reference/workflow-runs/stream-workflow-events) with `include_state_snapshot=true` to replay each executed node's status, then stream the rest.\n\nA finished run's node-level logs aren't available through the Service API.",
|
|
"operationId": "getWorkflowLogs",
|
|
"tags": [
|
|
"Workflow Runs"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "keyword",
|
|
"in": "query",
|
|
"description": "Keyword to search in logs.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "status",
|
|
"in": "query",
|
|
"description": "Filter by execution status.",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"succeeded",
|
|
"failed",
|
|
"stopped"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"name": "page",
|
|
"in": "query",
|
|
"description": "Page number.",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 1,
|
|
"minimum": 1,
|
|
"maximum": 99999
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Number of items per page.",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20,
|
|
"minimum": 1,
|
|
"maximum": 100
|
|
}
|
|
},
|
|
{
|
|
"name": "created_at__before",
|
|
"in": "query",
|
|
"description": "Filter logs created before this ISO 8601 timestamp.",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
{
|
|
"name": "created_at__after",
|
|
"in": "query",
|
|
"description": "Filter logs created after this ISO 8601 timestamp.",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
{
|
|
"name": "created_by_end_user_session_id",
|
|
"in": "query",
|
|
"description": "Filter by end user session ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "created_by_account",
|
|
"in": "query",
|
|
"description": "Filter by the creator's account email (e.g., `name@example.com`).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successfully retrieved workflow logs.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkflowLogsResponse"
|
|
},
|
|
"examples": {
|
|
"workflowLogs": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"page": 1,
|
|
"limit": 20,
|
|
"total": 1,
|
|
"has_more": false,
|
|
"data": [
|
|
{
|
|
"id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456",
|
|
"workflow_run": {
|
|
"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
|
|
"version": "2025-01-16 12:00:00.000000",
|
|
"status": "succeeded",
|
|
"error": null,
|
|
"elapsed_time": 1.23,
|
|
"total_tokens": 150,
|
|
"total_steps": 3,
|
|
"created_at": 1705407629,
|
|
"finished_at": 1705407630,
|
|
"exceptions_count": 0,
|
|
"triggered_from": "app-run"
|
|
},
|
|
"created_from": "service-api",
|
|
"created_by_role": "end_user",
|
|
"created_by_account": null,
|
|
"created_by_end_user": {
|
|
"id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
|
|
"type": "service-api",
|
|
"is_anonymous": false,
|
|
"session_id": "user_workflow_123"
|
|
},
|
|
"created_at": 1705407629
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : A query parameter is invalid, such as a `created_by_account` value matching no account, a malformed `created_at__before` or `created_at__after` timestamp, or an out-of-range `page`, `limit`, or `status` value.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Account not found: name@example.com"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/workflow-runs/list-workflow-logs",
|
|
"metadata": {
|
|
"title": "List Workflow Logs",
|
|
"sidebarTitle": "List Workflow Logs"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/form/human_input/{form_token}": {
|
|
"get": {
|
|
"tags": [
|
|
"Human Input"
|
|
],
|
|
"summary": "Get Human Input Form",
|
|
"description": "**Available for**: Chatflow, Workflow apps.\n\nReturns the contents of a paused Human Input form. Requires WebApp delivery.\n\nFor the full sequence of Human Input calls, see [Human Input Flow](/en/api-reference/guides/human-input-flow).",
|
|
"operationId": "getChatflowHumanInputForm",
|
|
"parameters": [
|
|
{
|
|
"name": "form_token",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Access token for the paused form, returned in the `human_input_required` event from the Run Workflow or Send Chat Message endpoint in streaming mode."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Form contents retrieved successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"form_content": {
|
|
"type": "string",
|
|
"description": "Pre-rendered form body with workflow variables substituted."
|
|
},
|
|
"inputs": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Form input control type. Available values: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads)."
|
|
},
|
|
"output_variable_name": {
|
|
"type": "string",
|
|
"description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object."
|
|
},
|
|
"default": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Raw default-value configuration for `paragraph` inputs. The client should not resolve this directly; use `resolved_default_values` to display defaults. absent for other input types or when no default is configured.",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable."
|
|
},
|
|
"selector": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements."
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"description": "Literal default value when `type` is `constant`. Always a string."
|
|
}
|
|
}
|
|
},
|
|
"option_source": {
|
|
"type": "object",
|
|
"description": "Source of options for `select` inputs. Present only when `type` is `select`.",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"variable",
|
|
"constant"
|
|
],
|
|
"description": "Origin of the options. `constant` means `value` lists the options literally; `variable` means `selector` points to an `array[string]` workflow variable that provides them."
|
|
},
|
|
"selector": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Variable reference path when `type` is `variable`."
|
|
},
|
|
"value": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Literal option list when `type` is `constant`."
|
|
}
|
|
}
|
|
},
|
|
"allowed_file_types": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string",
|
|
"enum": [
|
|
"image",
|
|
"document",
|
|
"audio",
|
|
"video",
|
|
"custom"
|
|
]
|
|
},
|
|
"description": "File categories the recipient may upload. Present for `file` and `file-list` inputs. Values: `image`, `document`, `audio`, `video`, `custom`."
|
|
},
|
|
"allowed_file_extensions": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Allowed file extensions when `allowed_file_types` includes `custom`. Include the leading `.` in each extension, for example `.md`. Present for `file` and `file-list` inputs."
|
|
},
|
|
"allowed_file_upload_methods": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string",
|
|
"enum": [
|
|
"local_file",
|
|
"remote_url"
|
|
]
|
|
},
|
|
"description": "Upload methods the recipient may use. Values: `local_file`, `remote_url`. Present for `file` and `file-list` inputs."
|
|
},
|
|
"number_limits": {
|
|
"type": "integer",
|
|
"description": "Maximum number of files the recipient may upload. Present only for `file-list` inputs."
|
|
}
|
|
}
|
|
},
|
|
"description": "Form input field definitions."
|
|
},
|
|
"resolved_default_values": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
},
|
|
"description": "Pre-rendered values to display in the form. Keyed by input `output_variable_name`. Populated for `paragraph` inputs whose default resolves from a workflow variable; empty for inputs with no resolvable default. Display these values; do not re-resolve `default` on the client. All values are stringified."
|
|
},
|
|
"user_actions": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"maxLength": 20,
|
|
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
|
|
"description": "Identifier of the action button. Pass as `action` on [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form) when the recipient selects this button."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"maxLength": 100,
|
|
"description": "Button label shown to the recipient."
|
|
},
|
|
"button_style": {
|
|
"type": "string",
|
|
"description": "Visual style of the button. Available values: `primary`, `default`, `accent`, `ghost`."
|
|
}
|
|
}
|
|
},
|
|
"description": "Available submission actions."
|
|
},
|
|
"expiration_time": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp (seconds) after which this form can no longer be submitted.",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"form_content": "Please review the draft, set a priority, and confirm or request changes.",
|
|
"inputs": [
|
|
{
|
|
"type": "paragraph",
|
|
"output_variable_name": "feedback",
|
|
"default": {
|
|
"type": "constant",
|
|
"selector": [],
|
|
"value": ""
|
|
}
|
|
},
|
|
{
|
|
"type": "select",
|
|
"output_variable_name": "priority",
|
|
"option_source": {
|
|
"type": "constant",
|
|
"selector": [],
|
|
"value": [
|
|
"low",
|
|
"medium",
|
|
"high"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"type": "file",
|
|
"output_variable_name": "attachment",
|
|
"allowed_file_types": [
|
|
"image",
|
|
"document"
|
|
],
|
|
"allowed_file_extensions": [],
|
|
"allowed_file_upload_methods": [
|
|
"local_file",
|
|
"remote_url"
|
|
]
|
|
},
|
|
{
|
|
"type": "file-list",
|
|
"output_variable_name": "attachments",
|
|
"allowed_file_types": [
|
|
"image",
|
|
"document"
|
|
],
|
|
"allowed_file_extensions": [],
|
|
"allowed_file_upload_methods": [
|
|
"local_file",
|
|
"remote_url"
|
|
],
|
|
"number_limits": 5
|
|
}
|
|
],
|
|
"resolved_default_values": {
|
|
"feedback": ""
|
|
},
|
|
"user_actions": [
|
|
{
|
|
"id": "approve",
|
|
"title": "Approve",
|
|
"button_style": "primary"
|
|
},
|
|
{
|
|
"id": "reject",
|
|
"title": "Request changes",
|
|
"button_style": "default"
|
|
}
|
|
],
|
|
"expiration_time": 1745510400
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Form not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Form not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"412": {
|
|
"description": "- `human_input_form_submitted` : Form already submitted. Forms are one-shot; the first response wins regardless of which user submits it.\n- `human_input_form_expired` : The form's expiration time passed before submission arrived.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"human_input_form_submitted": {
|
|
"summary": "human_input_form_submitted",
|
|
"value": {
|
|
"status": 412,
|
|
"code": "human_input_form_submitted",
|
|
"message": "This form has already been submitted by another user, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
}
|
|
},
|
|
"human_input_form_expired": {
|
|
"summary": "human_input_form_expired",
|
|
"value": {
|
|
"status": 412,
|
|
"code": "human_input_form_expired",
|
|
"message": "This form has expired, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/human-input/get-human-input-form",
|
|
"metadata": {
|
|
"title": "Get Human Input Form",
|
|
"sidebarTitle": "Get Human Input Form"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": [
|
|
"Human Input"
|
|
],
|
|
"summary": "Submit Human Input Form",
|
|
"description": "**Available for**: Chatflow, Workflow apps.\n\nSubmits the recipient's response to a paused Human Input form. On acceptance the workflow resumes; follow the resumed run via [Stream Workflow Events](/en/api-reference/workflow-runs/stream-workflow-events). Requires WebApp delivery.",
|
|
"operationId": "submitChatflowHumanInputForm",
|
|
"parameters": [
|
|
{
|
|
"name": "form_token",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Access token for the paused form, returned in the `human_input_required` event from the Run Workflow or Send Chat Message endpoint in streaming mode."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"inputs",
|
|
"action",
|
|
"user"
|
|
],
|
|
"properties": {
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Submitted values keyed by each input's `output_variable_name`. Paragraph and select inputs take a string; a `file` input takes one file mapping; a `file-list` input takes an array of file mappings.\n\nA file mapping is `{transfer_method: local_file, upload_file_id, type}` or `{transfer_method: remote_url, url, type}`, where `type` is one of the field's `allowed_file_types`. For `local_file`, `upload_file_id` is the `id` from [Upload File](/en/api-reference/files/upload-file).\n\nUse a consistent `user` across the run, upload, and submit."
|
|
},
|
|
"action": {
|
|
"type": "string",
|
|
"description": "ID of the action button the recipient selected. Must match one of the `id` values from the form's `user_actions` list (returned by [Get Human Input Form](/en/api-reference/human-input/get-human-input-form))."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. Service API and WebApp user IDs are separate, even when identical. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"approve": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"inputs": {
|
|
"feedback": "Looks good to ship",
|
|
"priority": "high",
|
|
"attachment": {
|
|
"transfer_method": "local_file",
|
|
"upload_file_id": "3c8fa1b2-7d4e-4f9a-b0c1-d2e3f4a5b6c7",
|
|
"type": "image"
|
|
},
|
|
"attachments": [
|
|
{
|
|
"transfer_method": "local_file",
|
|
"upload_file_id": "1a77f0df-c0e6-461c-987c-e72526f341ee",
|
|
"type": "document"
|
|
},
|
|
{
|
|
"transfer_method": "remote_url",
|
|
"url": "https://example.com/report.pdf",
|
|
"type": "document"
|
|
}
|
|
]
|
|
},
|
|
"action": "approve",
|
|
"user": "abc-123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Form submitted successfully. The response body is an empty object.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object"
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `bad_request` : Form recipient type is invalid.\n- `invalid_form_data` : Submission failed validation against the form definition.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"bad_request": {
|
|
"summary": "bad_request",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "bad_request",
|
|
"message": "Form recipient type is invalid"
|
|
}
|
|
},
|
|
"invalid_form_data": {
|
|
"summary": "invalid_form_data",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_form_data",
|
|
"message": "Missing required inputs: feedback"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Form not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Form not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"412": {
|
|
"description": "- `human_input_form_submitted` : Form already submitted. Forms are one-shot; the first response wins regardless of which user submits it.\n- `human_input_form_expired` : The form's expiration time passed before submission arrived.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"human_input_form_submitted": {
|
|
"summary": "human_input_form_submitted",
|
|
"value": {
|
|
"status": 412,
|
|
"code": "human_input_form_submitted",
|
|
"message": "This form has already been submitted by another user, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
}
|
|
},
|
|
"human_input_form_expired": {
|
|
"summary": "human_input_form_expired",
|
|
"value": {
|
|
"status": 412,
|
|
"code": "human_input_form_expired",
|
|
"message": "This form has expired, form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/human-input/submit-human-input-form",
|
|
"metadata": {
|
|
"title": "Submit Human Input Form",
|
|
"sidebarTitle": "Submit Human Input Form"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workflow/{workflow_run_id}/events": {
|
|
"get": {
|
|
"tags": [
|
|
"Workflow Runs"
|
|
],
|
|
"summary": "Stream Workflow Events",
|
|
"description": "**Available for**: Chatflow, Workflow apps.\n\nResume the Server-Sent Events stream for a workflow run after a pause or a dropped SSE connection. For runs that have already finished, the stream emits a single `workflow_finished` event and closes.\n\nTo check an in-progress run's node-level status and progress, call it with `include_state_snapshot=true`: the stream replays each already-executed node's status before streaming new events.",
|
|
"operationId": "streamWorkflowEvents",
|
|
"parameters": [
|
|
{
|
|
"name": "workflow_run_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Workflow run ID whose event stream to resume, from the response or streaming events of [Run Workflow](/en/api-reference/workflow-runs/run-workflow)."
|
|
},
|
|
{
|
|
"name": "user",
|
|
"in": "query",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "End-user identifier, defined by your app and unique within it. Must match the `user` that started the run. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
},
|
|
{
|
|
"name": "include_state_snapshot",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "boolean",
|
|
"default": false
|
|
},
|
|
"description": "When `true`, replay from the persisted state snapshot to include a status summary of already-executed nodes before streaming new events."
|
|
},
|
|
{
|
|
"name": "continue_on_pause",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "boolean",
|
|
"default": false
|
|
},
|
|
"description": "Set to `true` to keep the stream open across multiple `workflow_paused` events (useful when the workflow has more than one Human Input node in sequence). Default closes the stream after the first pause."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Server-Sent Events stream. Each event is delivered as `data: {JSON}\\n\\n`. Event payloads follow the same schemas as the original streaming response.",
|
|
"content": {
|
|
"text/event-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "SSE stream of events from a resumed workflow run, in the same format as [Run Workflow](/en/api-reference/workflow-runs/run-workflow) (Workflow apps) or [Send Chat Message](/en/api-reference/chat-messages/send-chat-message) (Chatflow apps). When the resumed portion runs an LLM node with `reasoning_format: separated`, this stream also carries `reasoning_chunk` events."
|
|
},
|
|
"examples": {
|
|
"resumedRun": {
|
|
"summary": "Response Example - Resumed run (Workflow)",
|
|
"value": "data: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\", \"submitted_data\": {\"comment\": \"Looks good.\"}}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_2\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Approved, now translating.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour\"}, \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}"
|
|
},
|
|
"resumedRunChatflow": {
|
|
"summary": "Response Example - Resumed run (Chatflow)",
|
|
"value": "data: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"Please review the draft.\", \"action_id\": \"approve\", \"action_text\": \"Approve\", \"submitted_data\": {\"comment\": \"Looks good.\"}}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"The reviewer approved the draft.\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"answer\": \"Approved\", \"created_at\": 1705407706} data: {\"event\": \"node_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"status\": \"succeeded\", \"elapsed_time\": 1.2, \"created_at\": 1705407705, \"finished_at\": 1705407706}} data: {\"event\": \"message_end\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"metadata\": {\"usage\": {\"total_tokens\": 42, \"latency\": 1.3}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`not_workflow_app` : Please check if your app mode matches the right API route.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_workflow_app": {
|
|
"summary": "not_workflow_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_workflow_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Workflow run not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Workflow run not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "Resume stream",
|
|
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
|
|
},
|
|
{
|
|
"lang": "bash",
|
|
"label": "With state snapshot",
|
|
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}&include_state_snapshot=true' \\\n --header 'Authorization: Bearer {api_key}'"
|
|
}
|
|
],
|
|
"x-mint": {
|
|
"href": "/en/api-reference/workflow-runs/stream-workflow-events",
|
|
"metadata": {
|
|
"title": "Stream Workflow Events",
|
|
"sidebarTitle": "Stream Workflow Events"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workflows/run": {
|
|
"post": {
|
|
"summary": "Run Workflow",
|
|
"description": "**Available for**: Workflow apps.\n\nRun the app's published workflow and return its outputs, either in a single `blocking` response or as a `streaming` Server-Sent Events feed. Requires a published workflow.",
|
|
"operationId": "executeWorkflow",
|
|
"tags": [
|
|
"Workflow Runs"
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkflowExecutionRequest"
|
|
},
|
|
"examples": {
|
|
"streaming_example": {
|
|
"summary": "Request Example - Streaming mode",
|
|
"value": {
|
|
"inputs": {
|
|
"query": "Summarize this text: The quick brown fox jumps over the lazy dog."
|
|
},
|
|
"response_mode": "streaming",
|
|
"user": "user_workflow_123"
|
|
}
|
|
},
|
|
"blocking_example": {
|
|
"summary": "Request Example - Blocking mode",
|
|
"value": {
|
|
"inputs": {
|
|
"query": "Translate this to French: Hello world"
|
|
},
|
|
"response_mode": "blocking",
|
|
"user": "user_workflow_456"
|
|
}
|
|
},
|
|
"with_file_array_variable": {
|
|
"summary": "Request Example - File array input",
|
|
"value": {
|
|
"inputs": {
|
|
"my_documents": [
|
|
{
|
|
"type": "document",
|
|
"transfer_method": "local_file",
|
|
"upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
|
|
},
|
|
{
|
|
"type": "image",
|
|
"transfer_method": "remote_url",
|
|
"url": "https://example.com/image.jpg"
|
|
}
|
|
]
|
|
},
|
|
"response_mode": "blocking",
|
|
"user": "user_workflow_789"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkflowBlockingResponse"
|
|
},
|
|
"examples": {
|
|
"blockingResponse": {
|
|
"summary": "Response Example - Blocking mode",
|
|
"value": {
|
|
"task_id": "c3800678-a077-43df-a102-53f23ed20b88",
|
|
"workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
|
|
"data": {
|
|
"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
|
|
"workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345",
|
|
"status": "succeeded",
|
|
"outputs": {
|
|
"result": "Bonjour le monde"
|
|
},
|
|
"error": null,
|
|
"elapsed_time": 1.23,
|
|
"total_tokens": 150,
|
|
"total_steps": 3,
|
|
"created_at": 1705407629,
|
|
"finished_at": 1705407630
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"text/event-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive every 10 seconds).\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries `message_id: null` and no `conversation_id`. The parallel `text_chunk` stream stays free of `<think>` tags.\n\n**Human Input events**:\n- `human_input_required`: Fires together with `workflow_paused` when the workflow reaches a Human Input node. Use the `form_token` from the payload to drive the form-handling flow via the [Human Input API](/en/api-reference/human-input/get-human-input-form).\n- `human_input_form_filled`: A recipient submitted the form; workflow execution resumes.\n- `human_input_form_timeout`: The form expired without a response. Workflow follows the timeout fallback edge if defined."
|
|
},
|
|
"examples": {
|
|
"streamingResponse": {
|
|
"summary": "Response Example - Streaming mode",
|
|
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}"
|
|
},
|
|
"humanInputPause": {
|
|
"summary": "Response Example - Human Input pause",
|
|
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : A request parameter is missing or invalid, such as a missing `user` or an unpublished workflow.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_workflow_app": {
|
|
"summary": "not_workflow_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_workflow_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"provider_quota_exceeded": {
|
|
"summary": "provider_quota_exceeded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_quota_exceeded",
|
|
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
|
|
}
|
|
},
|
|
"model_currently_not_support": {
|
|
"summary": "model_currently_not_support",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "model_currently_not_support",
|
|
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
|
|
}
|
|
},
|
|
"completion_request_error": {
|
|
"summary": "completion_request_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "completion_request_error",
|
|
"message": "Completion request failed."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Arg user must be provided."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"too_many_requests": {
|
|
"summary": "too_many_requests",
|
|
"value": {
|
|
"status": 429,
|
|
"code": "too_many_requests",
|
|
"message": "Too many requests. Please try again later."
|
|
}
|
|
},
|
|
"rate_limit_error": {
|
|
"summary": "rate_limit_error",
|
|
"value": {
|
|
"status": 429,
|
|
"code": "rate_limit_error",
|
|
"message": "Rate Limit Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`internal_server_error` : Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"internal_server_error": {
|
|
"summary": "internal_server_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "internal_server_error",
|
|
"message": "Internal Server Error."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/workflow-runs/run-workflow",
|
|
"metadata": {
|
|
"title": "Run Workflow",
|
|
"sidebarTitle": "Run Workflow"
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl -N --request POST \\\n --url 'https://{api_base_url}/workflows/run' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --data '{\"inputs\": {\"query\": \"Summarize this text: The quick brown fox jumps over the lazy dog.\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/workflows/{workflow_id}/run": {
|
|
"post": {
|
|
"summary": "Run Workflow by ID",
|
|
"description": "**Available for**: Workflow apps.\n\nRun a specific published workflow version, identified by the `workflow_id` in the path. Request body, response, and streaming behavior match [Run Workflow](/en/api-reference/workflow-runs/run-workflow); only the executed version differs.",
|
|
"operationId": "runWorkflowById",
|
|
"tags": [
|
|
"Workflow Runs"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "workflow_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Published workflow version to run. Returned in the `workflow_id` field of [Run Workflow](/en/api-reference/workflow-runs/run-workflow) responses and [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail). Must reference a published version; a draft version ID is rejected with `bad_request`.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkflowExecutionRequest"
|
|
},
|
|
"examples": {
|
|
"example": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"inputs": {
|
|
"query": "Summarize this article"
|
|
},
|
|
"response_mode": "blocking",
|
|
"user": "user_workflow_123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkflowBlockingResponse"
|
|
},
|
|
"examples": {
|
|
"blockingResponse": {
|
|
"summary": "Response Example - Blocking mode",
|
|
"value": {
|
|
"task_id": "c3800678-a077-43df-a102-53f23ed20b88",
|
|
"workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
|
|
"data": {
|
|
"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
|
|
"workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345",
|
|
"status": "succeeded",
|
|
"outputs": {
|
|
"result": "Article summary here"
|
|
},
|
|
"error": null,
|
|
"elapsed_time": 2.45,
|
|
"total_tokens": 280,
|
|
"total_steps": 4,
|
|
"created_at": 1705407629,
|
|
"finished_at": 1705407631
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"text/event-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive every 10 seconds).\n\n**Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code.\n\n**Reasoning events**:\n- `reasoning_chunk`: A chain-of-thought delta from an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning; an event with `is_final: true` marks the node finished thinking (and may carry an empty `reasoning`). The payload sits under `data` and, unlike chat apps, carries `message_id: null` and no `conversation_id`. The parallel `text_chunk` stream stays free of `<think>` tags.\n\n**Human Input events**:\n- `human_input_required`: Fires together with `workflow_paused` when the workflow reaches a Human Input node. Use the `form_token` from the payload to drive the form-handling flow via the [Human Input API](/en/api-reference/human-input/get-human-input-form).\n- `human_input_form_filled`: A recipient submitted the form; workflow execution resumes.\n- `human_input_form_timeout`: The form expired without a response. Workflow follows the timeout fallback edge if defined."
|
|
},
|
|
"examples": {
|
|
"streamingResponse": {
|
|
"summary": "Response Example - Streaming mode",
|
|
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}"
|
|
},
|
|
"humanInputPause": {
|
|
"summary": "Response Example - Human Input pause",
|
|
"value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"Please review the draft.\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"Approve\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : A request parameter is missing or invalid, such as a missing `user`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_workflow_app": {
|
|
"summary": "not_workflow_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_workflow_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
},
|
|
"bad_request": {
|
|
"summary": "bad_request",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "bad_request",
|
|
"message": "Cannot use draft workflow version. Workflow ID: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345. Please use a published workflow version or leave workflow_id empty."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"provider_quota_exceeded": {
|
|
"summary": "provider_quota_exceeded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_quota_exceeded",
|
|
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
|
|
}
|
|
},
|
|
"model_currently_not_support": {
|
|
"summary": "model_currently_not_support",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "model_currently_not_support",
|
|
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
|
|
}
|
|
},
|
|
"completion_request_error": {
|
|
"summary": "completion_request_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "completion_request_error",
|
|
"message": "Completion request failed."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Arg user must be provided."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`workflow_version_execution_not_allowed` : Executing a specific workflow version is not available on the Dify Cloud Sandbox plan.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"workflow_version_execution_not_allowed": {
|
|
"summary": "workflow_version_execution_not_allowed",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "workflow_version_execution_not_allowed",
|
|
"message": "Workflow version execution is not available on your current plan. Please upgrade to a paid plan."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Workflow not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Workflow not found with id: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"too_many_requests": {
|
|
"summary": "too_many_requests",
|
|
"value": {
|
|
"status": 429,
|
|
"code": "too_many_requests",
|
|
"message": "Too many requests. Please try again later."
|
|
}
|
|
},
|
|
"rate_limit_error": {
|
|
"summary": "rate_limit_error",
|
|
"value": {
|
|
"status": 429,
|
|
"code": "rate_limit_error",
|
|
"message": "Rate Limit Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`internal_server_error` : Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"internal_server_error": {
|
|
"summary": "internal_server_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "internal_server_error",
|
|
"message": "Internal Server Error."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/workflow-runs/run-workflow-by-id",
|
|
"metadata": {
|
|
"title": "Run Workflow by ID",
|
|
"sidebarTitle": "Run Workflow by ID"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workflows/tasks/{task_id}/stop": {
|
|
"post": {
|
|
"summary": "Stop Workflow Task",
|
|
"description": "**Available for**: Workflow apps.\n\nStop a running workflow task. Only supported in `streaming` mode.",
|
|
"operationId": "stopWorkflowTaskGeneration",
|
|
"tags": [
|
|
"Workflow Runs"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "task_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Task ID, from the streaming events of [Run Workflow](/en/api-reference/workflow-runs/run-workflow).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"user"
|
|
],
|
|
"properties": {
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. Need not match the `user` that started the run; the stop applies to the task regardless of `user`. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"example": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"user": "user_workflow_123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"$ref": "#/components/responses/SuccessResult"
|
|
},
|
|
"400": {
|
|
"description": "- `not_workflow_app` : App mode does not match the API route.\n- `invalid_param` : A request parameter is missing or invalid, such as a missing `user`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_workflow_app": {
|
|
"summary": "not_workflow_app",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "not_workflow_app",
|
|
"message": "Please check if your app mode matches the right API route."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Arg user must be provided."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/workflow-runs/stop-workflow-task",
|
|
"metadata": {
|
|
"title": "Stop Workflow Task",
|
|
"sidebarTitle": "Stop Workflow Task"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/completion-messages": {
|
|
"post": {
|
|
"summary": "Send Completion Message",
|
|
"description": "**Available for**: Text Generator apps.\n\nSends a request to a text-generation app and returns the generated text.",
|
|
"operationId": "createCompletionMessage",
|
|
"tags": [
|
|
"Completion Messages"
|
|
],
|
|
"requestBody": {
|
|
"description": "Request body to create a completion message.",
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CompletionRequest"
|
|
},
|
|
"examples": {
|
|
"streaming_example": {
|
|
"summary": "Request Example - Streaming mode",
|
|
"value": {
|
|
"inputs": {
|
|
"city": "San Francisco"
|
|
},
|
|
"query": "Translate 'hello' to Spanish.",
|
|
"response_mode": "streaming",
|
|
"user": "abc-123",
|
|
"files": [
|
|
{
|
|
"type": "image",
|
|
"transfer_method": "remote_url",
|
|
"url": "https://cloud.dify.ai/logo/logo-site.png"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"blocking_example": {
|
|
"summary": "Request Example - Blocking mode",
|
|
"value": {
|
|
"inputs": {
|
|
"city": "New York"
|
|
},
|
|
"query": "Summarize the following text: ...",
|
|
"response_mode": "blocking",
|
|
"user": "def-456"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkCompletionEvent` objects.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CompletionResponse"
|
|
},
|
|
"examples": {
|
|
"blockingResponse": {
|
|
"summary": "Response Example - Blocking mode",
|
|
"value": {
|
|
"event": "message",
|
|
"task_id": "c3800678-a077-43df-a102-53f23ed20b88",
|
|
"id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e",
|
|
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
|
|
"mode": "completion",
|
|
"answer": "Hello World!...",
|
|
"metadata": {
|
|
"usage": {
|
|
"prompt_tokens": 1033,
|
|
"prompt_unit_price": "0.001",
|
|
"prompt_price_unit": "0.001",
|
|
"prompt_price": "0.0010330",
|
|
"completion_tokens": 128,
|
|
"completion_unit_price": "0.002",
|
|
"completion_price_unit": "0.001",
|
|
"completion_price": "0.0002560",
|
|
"total_tokens": 1161,
|
|
"total_price": "0.0012890",
|
|
"currency": "USD",
|
|
"latency": 0.7682376249867957
|
|
}
|
|
},
|
|
"created_at": 1705407629
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"text/event-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "A stream of Server-Sent Events. Parse it per the [SSE Streaming guide](/en/api-reference/guides/streaming): read `data:` lines, dispatch on the `event` field, skip `ping` (keep-alive every 10 seconds). See `ChunkCompletionEvent` for the event structures.\n\n**Stream lifecycle**: the reply streams as `message` chunks and ends with `message_end`. An `error` event ends the stream early; HTTP status stays `200`, so inspect the event payload for details."
|
|
},
|
|
"examples": {
|
|
"streamingResponse": {
|
|
"summary": "Response Example - Streaming mode",
|
|
"value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.\n- `invalid_param` : The required `user` field is missing.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"app_unavailable": {
|
|
"summary": "app_unavailable",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "app_unavailable",
|
|
"message": "App unavailable, please check your app configurations."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"provider_quota_exceeded": {
|
|
"summary": "provider_quota_exceeded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_quota_exceeded",
|
|
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
|
|
}
|
|
},
|
|
"model_currently_not_support": {
|
|
"summary": "model_currently_not_support",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "model_currently_not_support",
|
|
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
|
|
}
|
|
},
|
|
"completion_request_error": {
|
|
"summary": "completion_request_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "completion_request_error",
|
|
"message": "Completion request failed."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Arg user must be provided."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"description": "`too_many_requests` : Too many concurrent requests for this app.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"too_many_requests": {
|
|
"summary": "too_many_requests",
|
|
"value": {
|
|
"status": 429,
|
|
"code": "too_many_requests",
|
|
"message": "Too many requests. Please try again later. The current maximum concurrent requests allowed for 5b3d4f2a-1c9e-4a7b-8f6d-2e0c9a1b3d4f is 10."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`internal_server_error` : Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"internal_server_error": {
|
|
"summary": "internal_server_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "internal_server_error",
|
|
"message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/completion-messages/send-completion-message",
|
|
"metadata": {
|
|
"title": "Send Completion Message",
|
|
"sidebarTitle": "Send Completion Message"
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl --request POST \\\n --url 'https://{api_base_url}/completion-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"inputs\": {\"city\": \"San Francisco\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/completion-messages/{task_id}/stop": {
|
|
"post": {
|
|
"summary": "Stop Completion Message Generation",
|
|
"description": "**Available for**: Text Generator apps.\n\nStops a completion message generation task. Only supported in `streaming` mode.",
|
|
"operationId": "stopGenerate",
|
|
"tags": [
|
|
"Completion Messages"
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "task_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Task ID, from the streaming events of [Send Completion Message](/en/api-reference/completion-messages/send-completion-message).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"user"
|
|
],
|
|
"properties": {
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. Must match the `user` sent with the original message; if it differs, the stop silently does nothing and still returns success. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"example": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"user": "abc-123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"$ref": "#/components/responses/SuccessResult"
|
|
},
|
|
"400": {
|
|
"description": "- `app_unavailable` : App unavailable or misconfigured.\n- `invalid_param` : The required `user` field is missing.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"app_unavailable": {
|
|
"summary": "app_unavailable",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "app_unavailable",
|
|
"message": "App unavailable, please check your app configurations."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Arg user must be provided."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/completion-messages/stop-completion-message-generation",
|
|
"metadata": {
|
|
"title": "Stop Completion Message Generation",
|
|
"sidebarTitle": "Stop Completion Message Generation"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets": {
|
|
"post": {
|
|
"tags": [
|
|
"Knowledge Bases"
|
|
],
|
|
"summary": "Create an Empty Knowledge Base",
|
|
"description": "Creates an empty knowledge base. Add documents to it with [Create Document by Text](/en/api-reference/documents/create-document-by-text) or [Create Document by File](/en/api-reference/documents/create-document-by-file).",
|
|
"operationId": "createDataset",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"name"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"maxLength": 40,
|
|
"description": "Name of the knowledge base."
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"maxLength": 400,
|
|
"default": "",
|
|
"description": "Description of the knowledge base."
|
|
},
|
|
"indexing_technique": {
|
|
"type": "string",
|
|
"enum": [
|
|
"high_quality",
|
|
"economy"
|
|
],
|
|
"nullable": true,
|
|
"description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing."
|
|
},
|
|
"permission": {
|
|
"type": "string",
|
|
"enum": [
|
|
"only_me",
|
|
"all_team_members",
|
|
"partial_members"
|
|
],
|
|
"default": "only_me",
|
|
"description": "Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members."
|
|
},
|
|
"provider": {
|
|
"type": "string",
|
|
"enum": [
|
|
"vendor",
|
|
"external"
|
|
],
|
|
"default": "vendor",
|
|
"description": "`vendor` for internal knowledge base, `external` for external knowledge base."
|
|
},
|
|
"embedding_model": {
|
|
"type": "string",
|
|
"description": "Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`."
|
|
},
|
|
"embedding_model_provider": {
|
|
"type": "string",
|
|
"description": "Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius/<name>/<name>` and works only for langgenius-published plugins.\n\nGet valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`."
|
|
},
|
|
"retrieval_model": {
|
|
"$ref": "#/components/schemas/RetrievalModel",
|
|
"description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base."
|
|
},
|
|
"external_knowledge_api_id": {
|
|
"type": "string",
|
|
"description": "ID of the external knowledge API connection."
|
|
},
|
|
"external_knowledge_id": {
|
|
"type": "string",
|
|
"description": "ID of the external knowledge base."
|
|
},
|
|
"summary_index_setting": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Summary index configuration.",
|
|
"properties": {
|
|
"enable": {
|
|
"type": "boolean",
|
|
"description": "Whether to enable summary indexing."
|
|
},
|
|
"model_name": {
|
|
"type": "string",
|
|
"description": "Name of the model used for generating summaries."
|
|
},
|
|
"model_provider_name": {
|
|
"type": "string",
|
|
"description": "Provider of the summary generation model."
|
|
},
|
|
"summary_prompt": {
|
|
"type": "string",
|
|
"description": "Custom prompt template for summary generation."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Knowledge base created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Dataset"
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
|
|
"name": "Product Documentation",
|
|
"description": "Technical documentation for the product API",
|
|
"provider": "vendor",
|
|
"permission": "only_me",
|
|
"data_source_type": null,
|
|
"indexing_technique": "high_quality",
|
|
"app_count": 0,
|
|
"document_count": 0,
|
|
"word_count": 0,
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"author_name": "admin",
|
|
"created_at": 1741267200,
|
|
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"updated_at": 1741267200,
|
|
"embedding_model": "text-embedding-3-small",
|
|
"embedding_model_provider": "langgenius/openai/openai",
|
|
"embedding_available": true,
|
|
"retrieval_model_dict": {
|
|
"search_method": "semantic_search",
|
|
"reranking_enable": false,
|
|
"reranking_mode": null,
|
|
"reranking_model": {
|
|
"reranking_provider_name": "",
|
|
"reranking_model_name": ""
|
|
},
|
|
"weights": null,
|
|
"top_k": 3,
|
|
"score_threshold_enabled": false,
|
|
"score_threshold": null
|
|
},
|
|
"tags": [],
|
|
"doc_form": "text_model",
|
|
"external_knowledge_info": null,
|
|
"external_retrieval_model": null,
|
|
"doc_metadata": [],
|
|
"built_in_field_enabled": true,
|
|
"pipeline_id": null,
|
|
"runtime_mode": null,
|
|
"chunk_structure": null,
|
|
"icon_info": null,
|
|
"summary_index_setting": null,
|
|
"is_published": false,
|
|
"total_documents": 0,
|
|
"total_available_documents": 0,
|
|
"enable_api": true,
|
|
"is_multimodal": false,
|
|
"maintainer": "admin"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The embedding or reranking model you specified is not configured or available.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Your subscription's knowledge base request rate limit has been reached.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"409": {
|
|
"description": "`dataset_name_duplicate` : A knowledge base with the same name already exists.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"dataset_name_duplicate": {
|
|
"summary": "dataset_name_duplicate",
|
|
"value": {
|
|
"status": 409,
|
|
"code": "dataset_name_duplicate",
|
|
"message": "The dataset name already exists. Please modify your dataset name."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-bases/create-an-empty-knowledge-base",
|
|
"metadata": {
|
|
"title": "Create an Empty Knowledge Base",
|
|
"sidebarTitle": "Create an Empty Knowledge Base"
|
|
}
|
|
}
|
|
},
|
|
"get": {
|
|
"tags": [
|
|
"Knowledge Bases"
|
|
],
|
|
"summary": "List Knowledge Bases",
|
|
"description": "Returns a paginated list of knowledge bases, optionally filtered by keyword or tags.",
|
|
"operationId": "listDatasets",
|
|
"parameters": [
|
|
{
|
|
"name": "page",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 1
|
|
},
|
|
"description": "Page number."
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20
|
|
},
|
|
"description": "Number of items per page."
|
|
},
|
|
{
|
|
"name": "keyword",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Search keyword to filter by name."
|
|
},
|
|
{
|
|
"name": "include_all",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "boolean",
|
|
"default": false
|
|
},
|
|
"description": "Whether to include all knowledge bases regardless of permissions."
|
|
},
|
|
{
|
|
"name": "tag_ids",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"style": "form",
|
|
"explode": true,
|
|
"description": "Tag IDs to filter by. Get tag IDs from [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of knowledge bases.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "Array of knowledge base objects.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Dataset"
|
|
}
|
|
},
|
|
"has_more": {
|
|
"type": "boolean",
|
|
"description": "Whether more items exist on the next page."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Number of items per page."
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total number of matching items."
|
|
},
|
|
"page": {
|
|
"type": "integer",
|
|
"description": "Current page number."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
|
|
"name": "Product Documentation",
|
|
"description": "Technical documentation for the product API",
|
|
"provider": "vendor",
|
|
"permission": "only_me",
|
|
"data_source_type": null,
|
|
"indexing_technique": "high_quality",
|
|
"app_count": 0,
|
|
"document_count": 0,
|
|
"word_count": 0,
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"author_name": "admin",
|
|
"created_at": 1741267200,
|
|
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"updated_at": 1741267200,
|
|
"embedding_model": "text-embedding-3-small",
|
|
"embedding_model_provider": "langgenius/openai/openai",
|
|
"embedding_available": true,
|
|
"retrieval_model_dict": {
|
|
"search_method": "semantic_search",
|
|
"reranking_enable": false,
|
|
"reranking_mode": null,
|
|
"reranking_model": {
|
|
"reranking_provider_name": "",
|
|
"reranking_model_name": ""
|
|
},
|
|
"weights": null,
|
|
"top_k": 3,
|
|
"score_threshold_enabled": false,
|
|
"score_threshold": null
|
|
},
|
|
"tags": [],
|
|
"doc_form": "text_model",
|
|
"external_knowledge_info": null,
|
|
"external_retrieval_model": null,
|
|
"doc_metadata": [],
|
|
"built_in_field_enabled": true,
|
|
"pipeline_id": null,
|
|
"runtime_mode": null,
|
|
"chunk_structure": null,
|
|
"icon_info": null,
|
|
"summary_index_setting": null,
|
|
"is_published": false,
|
|
"total_documents": 0,
|
|
"total_available_documents": 0,
|
|
"enable_api": true,
|
|
"is_multimodal": false,
|
|
"maintainer": "admin"
|
|
}
|
|
],
|
|
"has_more": false,
|
|
"limit": 20,
|
|
"total": 1,
|
|
"page": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-bases/list-knowledge-bases",
|
|
"metadata": {
|
|
"title": "List Knowledge Bases",
|
|
"sidebarTitle": "List Knowledge Bases"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Knowledge Bases"
|
|
],
|
|
"summary": "Get Knowledge Base",
|
|
"description": "Returns detailed information about a knowledge base, including its embedding model, retrieval configuration, and document statistics.",
|
|
"operationId": "getDatasetDetail",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Knowledge base details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Dataset"
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
|
|
"name": "Product Documentation",
|
|
"description": "Technical documentation for the product API",
|
|
"provider": "vendor",
|
|
"permission": "only_me",
|
|
"data_source_type": null,
|
|
"indexing_technique": "high_quality",
|
|
"app_count": 0,
|
|
"document_count": 0,
|
|
"word_count": 0,
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"author_name": "admin",
|
|
"created_at": 1741267200,
|
|
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"updated_at": 1741267200,
|
|
"embedding_model": "text-embedding-3-small",
|
|
"embedding_model_provider": "langgenius/openai/openai",
|
|
"embedding_available": true,
|
|
"retrieval_model_dict": {
|
|
"search_method": "semantic_search",
|
|
"reranking_enable": false,
|
|
"reranking_mode": null,
|
|
"reranking_model": {
|
|
"reranking_provider_name": "",
|
|
"reranking_model_name": ""
|
|
},
|
|
"weights": null,
|
|
"top_k": 3,
|
|
"score_threshold_enabled": false,
|
|
"score_threshold": null
|
|
},
|
|
"tags": [],
|
|
"doc_form": "text_model",
|
|
"external_knowledge_info": null,
|
|
"external_retrieval_model": null,
|
|
"doc_metadata": [],
|
|
"built_in_field_enabled": true,
|
|
"pipeline_id": null,
|
|
"runtime_mode": null,
|
|
"chunk_structure": null,
|
|
"icon_info": null,
|
|
"summary_index_setting": null,
|
|
"is_published": false,
|
|
"total_documents": 0,
|
|
"total_available_documents": 0,
|
|
"enable_api": true,
|
|
"is_multimodal": false,
|
|
"maintainer": "admin"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : API access is not enabled for this knowledge base.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : No knowledge base matches `dataset_id`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-bases/get-knowledge-base",
|
|
"metadata": {
|
|
"title": "Get Knowledge Base",
|
|
"sidebarTitle": "Get Knowledge Base"
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"tags": [
|
|
"Knowledge Bases"
|
|
],
|
|
"summary": "Update Knowledge Base",
|
|
"description": "Updates a knowledge base. Only the fields included in the request body are changed.",
|
|
"operationId": "updateDataset",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"maxLength": 40,
|
|
"description": "Name of the knowledge base."
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"maxLength": 400,
|
|
"description": "Description of the knowledge base."
|
|
},
|
|
"indexing_technique": {
|
|
"type": "string",
|
|
"enum": [
|
|
"high_quality",
|
|
"economy"
|
|
],
|
|
"nullable": true,
|
|
"description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing."
|
|
},
|
|
"permission": {
|
|
"type": "string",
|
|
"enum": [
|
|
"only_me",
|
|
"all_team_members",
|
|
"partial_members"
|
|
],
|
|
"description": "Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members."
|
|
},
|
|
"embedding_model": {
|
|
"type": "string",
|
|
"description": "Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`."
|
|
},
|
|
"embedding_model_provider": {
|
|
"type": "string",
|
|
"description": "Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius/<name>/<name>` and works only for langgenius-published plugins.\n\nGet valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`."
|
|
},
|
|
"retrieval_model": {
|
|
"$ref": "#/components/schemas/RetrievalModel",
|
|
"description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base."
|
|
},
|
|
"partial_member_list": {
|
|
"type": "array",
|
|
"description": "List of team members with access when `permission` is `partial_members`.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"user_id": {
|
|
"type": "string",
|
|
"description": "ID of the team member to grant access."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"external_retrieval_model": {
|
|
"type": "object",
|
|
"description": "Retrieval settings for external knowledge bases.",
|
|
"properties": {
|
|
"top_k": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results to return."
|
|
},
|
|
"score_threshold": {
|
|
"type": "number",
|
|
"description": "Minimum similarity score threshold for filtering results."
|
|
},
|
|
"score_threshold_enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether score threshold filtering is enabled."
|
|
}
|
|
}
|
|
},
|
|
"external_knowledge_id": {
|
|
"type": "string",
|
|
"description": "ID of the external knowledge base."
|
|
},
|
|
"external_knowledge_api_id": {
|
|
"type": "string",
|
|
"description": "ID of the external knowledge API connection."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Knowledge base updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Dataset"
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
|
|
"name": "Product Documentation",
|
|
"description": "Technical documentation for the product API",
|
|
"provider": "vendor",
|
|
"permission": "only_me",
|
|
"data_source_type": null,
|
|
"indexing_technique": "high_quality",
|
|
"app_count": 0,
|
|
"document_count": 0,
|
|
"word_count": 0,
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"author_name": "admin",
|
|
"created_at": 1741267200,
|
|
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"updated_at": 1741267200,
|
|
"embedding_model": "text-embedding-3-small",
|
|
"embedding_model_provider": "langgenius/openai/openai",
|
|
"embedding_available": true,
|
|
"retrieval_model_dict": {
|
|
"search_method": "semantic_search",
|
|
"reranking_enable": false,
|
|
"reranking_mode": null,
|
|
"reranking_model": {
|
|
"reranking_provider_name": "",
|
|
"reranking_model_name": ""
|
|
},
|
|
"weights": null,
|
|
"top_k": 3,
|
|
"score_threshold_enabled": false,
|
|
"score_threshold": null
|
|
},
|
|
"tags": [],
|
|
"doc_form": "text_model",
|
|
"external_knowledge_info": null,
|
|
"external_retrieval_model": null,
|
|
"doc_metadata": [],
|
|
"built_in_field_enabled": true,
|
|
"pipeline_id": null,
|
|
"runtime_mode": null,
|
|
"chunk_structure": null,
|
|
"icon_info": null,
|
|
"summary_index_setting": null,
|
|
"is_published": false,
|
|
"total_documents": 0,
|
|
"total_available_documents": 0,
|
|
"enable_api": true,
|
|
"is_multimodal": false,
|
|
"maintainer": "admin",
|
|
"partial_member_list": []
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The embedding or reranking model you specified is not configured or available.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : Your subscription's knowledge base request rate limit has been reached.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : No knowledge base matches `dataset_id`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-bases/update-knowledge-base",
|
|
"metadata": {
|
|
"title": "Update Knowledge Base",
|
|
"sidebarTitle": "Update Knowledge Base"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Knowledge Bases"
|
|
],
|
|
"summary": "Delete Knowledge Base",
|
|
"description": "Permanently deletes a knowledge base and all of its documents.",
|
|
"operationId": "deleteDataset",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "Knowledge base deleted successfully."
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : Your subscription's knowledge base request rate limit has been reached.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : No knowledge base matches `dataset_id`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-bases/delete-knowledge-base",
|
|
"metadata": {
|
|
"title": "Delete Knowledge Base",
|
|
"sidebarTitle": "Delete Knowledge Base"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/document/create-by-text": {
|
|
"post": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Create Document by Text",
|
|
"description": "Creates a document in a knowledge base from raw text. Indexing runs asynchronously; track it with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).",
|
|
"operationId": "createDocumentFromText",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"name",
|
|
"text"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Document name."
|
|
},
|
|
"text": {
|
|
"type": "string",
|
|
"description": "Document text content."
|
|
},
|
|
"indexing_technique": {
|
|
"type": "string",
|
|
"enum": [
|
|
"high_quality",
|
|
"economy"
|
|
],
|
|
"description": "Required when adding the first document to a knowledge base. Subsequent documents inherit the knowledge base's indexing technique if omitted. `high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing."
|
|
},
|
|
"doc_form": {
|
|
"type": "string",
|
|
"enum": [
|
|
"text_model",
|
|
"hierarchical_model",
|
|
"qa_model"
|
|
],
|
|
"default": "text_model",
|
|
"description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction."
|
|
},
|
|
"doc_language": {
|
|
"type": "string",
|
|
"default": "English",
|
|
"description": "Language of the document for processing optimization."
|
|
},
|
|
"process_rule": {
|
|
"type": "object",
|
|
"description": "Processing rules for chunking.",
|
|
"required": [
|
|
"mode"
|
|
],
|
|
"properties": {
|
|
"mode": {
|
|
"type": "string",
|
|
"enum": [
|
|
"automatic",
|
|
"custom",
|
|
"hierarchical"
|
|
],
|
|
"description": "`automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`)."
|
|
},
|
|
"rules": {
|
|
"type": "object",
|
|
"properties": {
|
|
"pre_processing_rules": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"enum": [
|
|
"remove_stopwords",
|
|
"remove_extra_spaces",
|
|
"remove_urls_emails"
|
|
],
|
|
"description": "Rule identifier."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether this preprocessing rule is enabled."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"segmentation": {
|
|
"type": "object",
|
|
"properties": {
|
|
"separator": {
|
|
"type": "string",
|
|
"default": "\n",
|
|
"description": "Custom separator for splitting text."
|
|
},
|
|
"max_tokens": {
|
|
"type": "integer",
|
|
"description": "Maximum token count per chunk."
|
|
},
|
|
"chunk_overlap": {
|
|
"type": "integer",
|
|
"default": 0,
|
|
"description": "Token overlap between chunks."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"retrieval_model": {
|
|
"$ref": "#/components/schemas/RetrievalModel",
|
|
"description": "Controls how chunks are searched and ranked when querying this knowledge base."
|
|
},
|
|
"embedding_model": {
|
|
"type": "string",
|
|
"description": "Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`."
|
|
},
|
|
"embedding_model_provider": {
|
|
"type": "string",
|
|
"description": "Embedding model provider. Use the `provider` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`."
|
|
},
|
|
"original_document_id": {
|
|
"type": "string",
|
|
"description": "Original document ID for versioning. Get it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"document": {
|
|
"$ref": "#/components/schemas/Document"
|
|
},
|
|
"batch": {
|
|
"type": "string",
|
|
"description": "Batch ID for tracking indexing progress."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"document": {
|
|
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"position": 1,
|
|
"data_source_type": "upload_file",
|
|
"data_source_info": {
|
|
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
},
|
|
"data_source_detail_dict": {
|
|
"upload_file": {
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"name": "guide.txt",
|
|
"size": 2048,
|
|
"extension": "txt",
|
|
"mime_type": "text/plain",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200
|
|
}
|
|
},
|
|
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
|
|
"name": "guide.txt",
|
|
"created_from": "api",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"tokens": 0,
|
|
"indexing_status": "indexing",
|
|
"error": null,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"archived": false,
|
|
"display_status": "indexing",
|
|
"word_count": 0,
|
|
"hit_count": 0,
|
|
"doc_form": "text_model",
|
|
"doc_metadata": [],
|
|
"summary_index_status": null,
|
|
"need_summary": false
|
|
},
|
|
"batch": "20250306150245647595"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : `indexing_technique` is required when adding the first document, or `doc_form` is invalid.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"invalid_param_indexing": {
|
|
"summary": "invalid_param (indexing_technique)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "indexing_technique is required."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : The number of documents has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (vector space)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The capacity of the vector space has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (documents limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The number of documents has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_4": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Knowledge base not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/create-document-by-text",
|
|
"metadata": {
|
|
"title": "Create Document by Text",
|
|
"sidebarTitle": "Create Document by Text"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/document/create-by-file": {
|
|
"post": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Create Document by File",
|
|
"description": "Creates a document in a knowledge base from an uploaded file. Common formats such as PDF, TXT, and DOCX are supported. Indexing runs asynchronously; track it with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).",
|
|
"operationId": "createDocumentFromFile",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"file"
|
|
],
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "File to upload."
|
|
},
|
|
"data": {
|
|
"type": "string",
|
|
"description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`indexing_technique`, `doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.",
|
|
"example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"document": {
|
|
"$ref": "#/components/schemas/Document"
|
|
},
|
|
"batch": {
|
|
"type": "string",
|
|
"description": "Batch ID for tracking indexing progress."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"document": {
|
|
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"position": 1,
|
|
"data_source_type": "upload_file",
|
|
"data_source_info": {
|
|
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
},
|
|
"data_source_detail_dict": {
|
|
"upload_file": {
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"name": "guide.txt",
|
|
"size": 2048,
|
|
"extension": "txt",
|
|
"mime_type": "text/plain",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200
|
|
}
|
|
},
|
|
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
|
|
"name": "guide.txt",
|
|
"created_from": "api",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"tokens": 0,
|
|
"indexing_status": "indexing",
|
|
"error": null,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"archived": false,
|
|
"display_status": "indexing",
|
|
"word_count": 0,
|
|
"hit_count": 0,
|
|
"doc_form": "text_model",
|
|
"doc_metadata": [],
|
|
"summary_index_status": null,
|
|
"need_summary": false
|
|
},
|
|
"batch": "20250306150245647595"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : The knowledge base is external, `indexing_technique` is required, or `process_rule` is missing.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"no_file_uploaded": {
|
|
"summary": "no_file_uploaded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "no_file_uploaded",
|
|
"message": "Please upload your file."
|
|
}
|
|
},
|
|
"too_many_files": {
|
|
"summary": "too_many_files",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "too_many_files",
|
|
"message": "Only one file is allowed."
|
|
}
|
|
},
|
|
"filename_not_exists_error": {
|
|
"summary": "filename_not_exists_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "filename_not_exists_error",
|
|
"message": "The specified filename does not exist."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"invalid_param_external": {
|
|
"summary": "invalid_param (external)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "External datasets are not supported."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : The number of documents has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (vector space)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The capacity of the vector space has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (documents limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The number of documents has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_4": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Knowledge base not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/create-document-by-file",
|
|
"metadata": {
|
|
"title": "Create Document by File",
|
|
"sidebarTitle": "Create Document by File"
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/document/create-by-file' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents": {
|
|
"get": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "List Documents",
|
|
"description": "Returns a paginated list of documents in a knowledge base.",
|
|
"operationId": "listDocuments",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "page",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 1
|
|
},
|
|
"description": "Page number."
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20
|
|
},
|
|
"description": "Number of items per page. Server caps at `100`."
|
|
},
|
|
{
|
|
"name": "keyword",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Search keyword to filter by document name."
|
|
},
|
|
{
|
|
"name": "status",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"queuing",
|
|
"indexing",
|
|
"paused",
|
|
"error",
|
|
"available",
|
|
"disabled",
|
|
"archived"
|
|
]
|
|
},
|
|
"description": "Filter by display status."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of documents.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "Array of document objects.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Document"
|
|
}
|
|
},
|
|
"has_more": {
|
|
"type": "boolean",
|
|
"description": "Whether more items exist on the next page."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Number of items per page."
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total number of matching items."
|
|
},
|
|
"page": {
|
|
"type": "integer",
|
|
"description": "Current page number."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"position": 1,
|
|
"data_source_type": "upload_file",
|
|
"data_source_info": {
|
|
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
},
|
|
"data_source_detail_dict": {
|
|
"upload_file": {
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"name": "guide.txt",
|
|
"size": 2048,
|
|
"extension": "txt",
|
|
"mime_type": "text/plain",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200
|
|
}
|
|
},
|
|
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
|
|
"name": "guide.txt",
|
|
"created_from": "api",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"tokens": 512,
|
|
"indexing_status": "completed",
|
|
"error": null,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"archived": false,
|
|
"display_status": "available",
|
|
"word_count": 350,
|
|
"hit_count": 0,
|
|
"doc_form": "text_model",
|
|
"doc_metadata": [],
|
|
"summary_index_status": null,
|
|
"need_summary": false
|
|
}
|
|
],
|
|
"has_more": false,
|
|
"limit": 20,
|
|
"total": 1,
|
|
"page": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Knowledge base API access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Knowledge base not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/list-documents",
|
|
"metadata": {
|
|
"title": "List Documents",
|
|
"sidebarTitle": "List Documents"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/{document_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Get Document",
|
|
"description": "Returns detailed information for a single document.",
|
|
"operationId": "getDocumentDetail",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
{
|
|
"name": "metadata",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"all",
|
|
"only",
|
|
"without"
|
|
],
|
|
"default": "all"
|
|
},
|
|
"description": "`all` returns all fields including metadata. `only` returns only `id`, `doc_type`, and `doc_metadata`. `without` returns all fields except `doc_metadata`."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document details. The returned fields depend on the `metadata` query parameter.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Document identifier."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Position index within the knowledge base."
|
|
},
|
|
"data_source_type": {
|
|
"type": "string",
|
|
"description": "How the document was uploaded. `upload_file` for file uploads, `notion_import` for Notion imports."
|
|
},
|
|
"data_source_info": {
|
|
"type": "object",
|
|
"description": "Data source details. For file uploads, this detail endpoint returns the full file object under `upload_file` (the list endpoint returns only `upload_file_id`).",
|
|
"properties": {
|
|
"upload_file": {
|
|
"type": "object",
|
|
"description": "Uploaded file details. Present when `data_source_type` is `upload_file`.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "File identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Original file name."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "File size in bytes."
|
|
},
|
|
"extension": {
|
|
"type": "string",
|
|
"description": "File extension."
|
|
},
|
|
"mime_type": {
|
|
"type": "string",
|
|
"description": "File MIME type."
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "ID of the user who uploaded the file."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"description": "Unix timestamp of file upload."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"dataset_process_rule_id": {
|
|
"type": "string",
|
|
"description": "ID of the processing rule applied to this document."
|
|
},
|
|
"dataset_process_rule": {
|
|
"type": "object",
|
|
"description": "Knowledge-base-level processing rule configuration."
|
|
},
|
|
"document_process_rule": {
|
|
"type": "object",
|
|
"description": "Document-level processing rule configuration."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Document name."
|
|
},
|
|
"created_from": {
|
|
"type": "string",
|
|
"description": "Origin of the document. `api` for API creation, `web` for UI creation."
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "ID of the user who created the document."
|
|
},
|
|
"created_at": {
|
|
"type": "number",
|
|
"description": "Unix timestamp of document creation."
|
|
},
|
|
"tokens": {
|
|
"type": "integer",
|
|
"description": "Number of tokens in the document."
|
|
},
|
|
"indexing_status": {
|
|
"type": "string",
|
|
"description": "Current indexing status, e.g. `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, `error`, `paused`."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if indexing failed, `null` otherwise."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether the document is enabled for retrieval."
|
|
},
|
|
"disabled_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Unix timestamp when the document was disabled, `null` if enabled."
|
|
},
|
|
"disabled_by": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the user who disabled the document, `null` if enabled."
|
|
},
|
|
"archived": {
|
|
"type": "boolean",
|
|
"description": "Whether the document is archived."
|
|
},
|
|
"display_status": {
|
|
"type": "string",
|
|
"description": "Display-friendly indexing status for the UI."
|
|
},
|
|
"hit_count": {
|
|
"type": "integer",
|
|
"description": "Number of times this document has been retrieved."
|
|
},
|
|
"doc_form": {
|
|
"type": "string",
|
|
"description": "Document chunking mode. `text_model` for standard text, `hierarchical_model` for parent-child, `qa_model` for QA pairs."
|
|
},
|
|
"doc_language": {
|
|
"type": "string",
|
|
"description": "Language of the document content."
|
|
},
|
|
"doc_type": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Document type classification, `null` if not set."
|
|
},
|
|
"doc_metadata": {
|
|
"type": "array",
|
|
"description": "Custom metadata key-value pairs for this document.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Metadata field identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Metadata field name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Metadata field type."
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"description": "Metadata field value for this document."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"completed_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Unix timestamp when processing completed, `null` if not yet completed."
|
|
},
|
|
"updated_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Unix timestamp of last update, `null` if never updated."
|
|
},
|
|
"indexing_latency": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Time taken for indexing in seconds, `null` if not completed."
|
|
},
|
|
"segment_count": {
|
|
"type": "integer",
|
|
"description": "Number of chunks in the document."
|
|
},
|
|
"average_segment_length": {
|
|
"type": "number",
|
|
"description": "Average character length of chunks."
|
|
},
|
|
"summary_index_status": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Status of summary indexing, `null` if summary index is not enabled."
|
|
},
|
|
"need_summary": {
|
|
"type": "boolean",
|
|
"description": "Whether the document needs summary generation."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"position": 1,
|
|
"data_source_type": "upload_file",
|
|
"data_source_info": {
|
|
"upload_file": {
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"name": "guide.txt",
|
|
"size": 2048,
|
|
"extension": "txt",
|
|
"mime_type": "text/plain",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200
|
|
}
|
|
},
|
|
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
|
|
"dataset_process_rule": {
|
|
"id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
|
|
"mode": "custom"
|
|
},
|
|
"document_process_rule": {
|
|
"mode": "custom",
|
|
"rules": {
|
|
"pre_processing_rules": [],
|
|
"segmentation": {
|
|
"separator": "###",
|
|
"max_tokens": 500,
|
|
"chunk_overlap": 50
|
|
}
|
|
}
|
|
},
|
|
"name": "guide.txt",
|
|
"created_from": "api",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"tokens": 512,
|
|
"indexing_status": "completed",
|
|
"error": null,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"archived": false,
|
|
"display_status": "available",
|
|
"hit_count": 0,
|
|
"doc_form": "text_model",
|
|
"doc_language": "English",
|
|
"doc_type": null,
|
|
"doc_metadata": [],
|
|
"completed_at": 1741267260,
|
|
"updated_at": 1741267260,
|
|
"indexing_latency": 60.0,
|
|
"segment_count": 5,
|
|
"average_segment_length": 70.0,
|
|
"summary_index_status": null,
|
|
"need_summary": false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_metadata` : The `metadata` query parameter value is invalid (must be `all`, `only`, or `without`).",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_metadata": {
|
|
"summary": "invalid_metadata",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_metadata",
|
|
"message": "Invalid metadata value: only"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : You do not have permission to access this document.\n- `forbidden` : Knowledge base API access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (no permission)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "No permission."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Document not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/get-document",
|
|
"metadata": {
|
|
"title": "Get Document",
|
|
"sidebarTitle": "Get Document"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Delete Document",
|
|
"description": "Permanently deletes a document and all its chunks from the knowledge base.",
|
|
"operationId": "deleteDocument",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "Success."
|
|
},
|
|
"403": {
|
|
"description": "- `archived_document_immutable` : The archived document is not editable.\n- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"archived_document_immutable": {
|
|
"summary": "archived_document_immutable",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "archived_document_immutable",
|
|
"message": "The archived document is not editable."
|
|
}
|
|
},
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : The document does not exist. Also returned as \"Dataset not found.\" when the knowledge base itself does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document Not Exists."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found_2",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/delete-document",
|
|
"metadata": {
|
|
"title": "Delete Document",
|
|
"sidebarTitle": "Delete Document"
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Update Document",
|
|
"description": "Updates a document by uploading a new file, then re-indexes it. This is the canonical endpoint for file-based document updates. Track progress with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).",
|
|
"operationId": "updateDocument",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "File to upload."
|
|
},
|
|
"data": {
|
|
"type": "string",
|
|
"description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.",
|
|
"example": "{\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"document": {
|
|
"$ref": "#/components/schemas/Document"
|
|
},
|
|
"batch": {
|
|
"type": "string",
|
|
"description": "Batch ID for tracking indexing progress."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"document": {
|
|
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"position": 1,
|
|
"data_source_type": "upload_file",
|
|
"data_source_info": {
|
|
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
},
|
|
"data_source_detail_dict": {
|
|
"upload_file": {
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"name": "guide.txt",
|
|
"size": 2048,
|
|
"extension": "txt",
|
|
"mime_type": "text/plain",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200
|
|
}
|
|
},
|
|
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
|
|
"name": "guide.txt",
|
|
"created_from": "api",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"tokens": 512,
|
|
"indexing_status": "completed",
|
|
"error": null,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"archived": false,
|
|
"display_status": "available",
|
|
"word_count": 350,
|
|
"hit_count": 0,
|
|
"doc_form": "text_model",
|
|
"doc_metadata": [],
|
|
"summary_index_status": null,
|
|
"need_summary": false
|
|
},
|
|
"batch": "20250306150245647595"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : The document is not available for update (only available documents can be updated).",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"too_many_files": {
|
|
"summary": "too_many_files",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "too_many_files",
|
|
"message": "Only one file is allowed."
|
|
}
|
|
},
|
|
"filename_not_exists_error": {
|
|
"summary": "filename_not_exists_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "filename_not_exists_error",
|
|
"message": "The specified filename does not exist."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"invalid_param_not_available": {
|
|
"summary": "invalid_param (not available)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Document is not available"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (vector space)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The capacity of the vector space has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Knowledge base not found.\n- `not_found` : Document not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"413": {
|
|
"description": "`file_too_large` : The uploaded file exceeds the maximum size.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"file_too_large": {
|
|
"summary": "file_too_large",
|
|
"value": {
|
|
"status": 413,
|
|
"code": "file_too_large",
|
|
"message": "File size exceeded."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"415": {
|
|
"description": "`unsupported_file_type` : The uploaded file's type is not supported.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"unsupported_file_type": {
|
|
"summary": "unsupported_file_type",
|
|
"value": {
|
|
"status": 415,
|
|
"code": "unsupported_file_type",
|
|
"message": "File type not allowed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/update-document",
|
|
"metadata": {
|
|
"title": "Update Document",
|
|
"sidebarTitle": "Update Document"
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl --request PATCH \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/documents/{document_id}' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/{document_id}/download": {
|
|
"get": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Download Document",
|
|
"description": "Returns a signed URL for downloading a document's original uploaded file.",
|
|
"operationId": "downloadDocument",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Download URL generated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"url": {
|
|
"type": "string",
|
|
"description": "Signed URL to download the original uploaded file."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : You do not have permission to access this document.\n- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (no permission)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "No permission."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Document not found. Also returned as \"Uploaded file not found.\" when the stored file is missing, and \"Document does not have an uploaded file to download.\" for non-file documents.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found_2",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Uploaded file not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found_3",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document does not have an uploaded file to download."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/download-document",
|
|
"metadata": {
|
|
"title": "Download Document",
|
|
"sidebarTitle": "Download Document"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/{batch}/indexing-status": {
|
|
"get": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Get Document Indexing Status",
|
|
"description": "Returns indexing progress for every document in a batch: the current stage and chunk completion counts. Poll until each `indexing_status` reaches `completed` or `error`. Status advances through `waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`.",
|
|
"operationId": "getDocumentIndexingStatus",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "batch",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Batch ID returned when you create or update a document."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Indexing status for documents in the batch.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of indexing status entries.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Document identifier."
|
|
},
|
|
"indexing_status": {
|
|
"type": "string",
|
|
"description": "Current indexing status: `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, or `error`."
|
|
},
|
|
"processing_started_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Unix timestamp when processing started."
|
|
},
|
|
"parsing_completed_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Unix timestamp when parsing completed."
|
|
},
|
|
"cleaning_completed_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Unix timestamp when cleaning completed."
|
|
},
|
|
"splitting_completed_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Unix timestamp when splitting completed."
|
|
},
|
|
"completed_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Unix timestamp when indexing completed."
|
|
},
|
|
"paused_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when indexing was paused. `null` if not paused."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if indexing failed. `null` if no error."
|
|
},
|
|
"stopped_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when indexing was stopped. `null` if not stopped."
|
|
},
|
|
"completed_segments": {
|
|
"type": "integer",
|
|
"description": "Number of chunks that have been indexed."
|
|
},
|
|
"total_segments": {
|
|
"type": "integer",
|
|
"description": "Total number of chunks to be indexed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"indexing_status": "completed",
|
|
"processing_started_at": 1741267200,
|
|
"parsing_completed_at": 1741267200,
|
|
"cleaning_completed_at": 1741267200,
|
|
"splitting_completed_at": 1741267200,
|
|
"completed_at": 1741267200,
|
|
"paused_at": null,
|
|
"error": null,
|
|
"stopped_at": null,
|
|
"completed_segments": 5,
|
|
"total_segments": 5
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Knowledge base API access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Knowledge base not found.\n- `not_found` : Documents not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"dataset_not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"documents_not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Documents not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/get-document-indexing-status",
|
|
"metadata": {
|
|
"title": "Get Document Indexing Status",
|
|
"sidebarTitle": "Get Document Indexing Status"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/{document_id}/update-by-text": {
|
|
"post": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Update Document by Text",
|
|
"description": "Updates a document's text content, name, or processing configuration. Re-indexes the document when its text changes.",
|
|
"operationId": "updateDocumentByText",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Document name. Required when `text` is provided."
|
|
},
|
|
"text": {
|
|
"type": "string",
|
|
"description": "Document text content."
|
|
},
|
|
"process_rule": {
|
|
"type": "object",
|
|
"description": "Processing rules for chunking.",
|
|
"required": [
|
|
"mode"
|
|
],
|
|
"properties": {
|
|
"mode": {
|
|
"type": "string",
|
|
"enum": [
|
|
"automatic",
|
|
"custom",
|
|
"hierarchical"
|
|
],
|
|
"description": "`automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`)."
|
|
},
|
|
"rules": {
|
|
"type": "object",
|
|
"properties": {
|
|
"pre_processing_rules": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"enum": [
|
|
"remove_stopwords",
|
|
"remove_extra_spaces",
|
|
"remove_urls_emails"
|
|
],
|
|
"description": "Rule identifier."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether this preprocessing rule is enabled."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"segmentation": {
|
|
"type": "object",
|
|
"properties": {
|
|
"separator": {
|
|
"type": "string",
|
|
"default": "\n",
|
|
"description": "Custom separator for splitting text."
|
|
},
|
|
"max_tokens": {
|
|
"type": "integer",
|
|
"description": "Maximum token count per chunk."
|
|
},
|
|
"chunk_overlap": {
|
|
"type": "integer",
|
|
"default": 0,
|
|
"description": "Token overlap between chunks."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"doc_form": {
|
|
"type": "string",
|
|
"enum": [
|
|
"text_model",
|
|
"hierarchical_model",
|
|
"qa_model"
|
|
],
|
|
"default": "text_model",
|
|
"description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction."
|
|
},
|
|
"doc_language": {
|
|
"type": "string",
|
|
"default": "English",
|
|
"description": "Language of the document for processing optimization."
|
|
},
|
|
"retrieval_model": {
|
|
"$ref": "#/components/schemas/RetrievalModel",
|
|
"description": "Controls how chunks are searched and ranked when querying this knowledge base."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"document": {
|
|
"$ref": "#/components/schemas/Document"
|
|
},
|
|
"batch": {
|
|
"type": "string",
|
|
"description": "Batch ID for tracking indexing progress."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"document": {
|
|
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"position": 1,
|
|
"data_source_type": "upload_file",
|
|
"data_source_info": {
|
|
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
},
|
|
"data_source_detail_dict": {
|
|
"upload_file": {
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"name": "guide.txt",
|
|
"size": 2048,
|
|
"extension": "txt",
|
|
"mime_type": "text/plain",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200
|
|
}
|
|
},
|
|
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
|
|
"name": "guide.txt",
|
|
"created_from": "api",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"tokens": 512,
|
|
"indexing_status": "completed",
|
|
"error": null,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"archived": false,
|
|
"display_status": "available",
|
|
"word_count": 350,
|
|
"hit_count": 0,
|
|
"doc_form": "text_model",
|
|
"doc_metadata": [],
|
|
"summary_index_status": null,
|
|
"need_summary": false
|
|
},
|
|
"batch": "20250306150245647595"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : `name` is required when `text` is provided, or `doc_form` is invalid.\n- `invalid_param` : The document is not available for update (only available documents can be updated).",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"invalid_param_name": {
|
|
"summary": "invalid_param (name required)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "name is required when text is provided."
|
|
}
|
|
},
|
|
"invalid_param_not_available": {
|
|
"summary": "invalid_param (not available)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Document is not available"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (vector space)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The capacity of the vector space has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Knowledge base not found.\n- `not_found` : Document not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/update-document-by-text",
|
|
"metadata": {
|
|
"title": "Update Document by Text",
|
|
"sidebarTitle": "Update Document by Text"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/{document_id}/update-by-file": {
|
|
"post": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Update Document by File",
|
|
"description": "Deprecated. Use [Update Document](/en/api-reference/documents/update-document) instead. Updates a document by uploading a new file, then re-indexes it.",
|
|
"operationId": "updateDocumentByFile",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. From [List Documents](/en/api-reference/documents/list-documents)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "File to upload."
|
|
},
|
|
"data": {
|
|
"type": "string",
|
|
"description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.",
|
|
"example": "{\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"document": {
|
|
"$ref": "#/components/schemas/Document"
|
|
},
|
|
"batch": {
|
|
"type": "string",
|
|
"description": "Batch ID for tracking indexing progress."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"document": {
|
|
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"position": 1,
|
|
"data_source_type": "upload_file",
|
|
"data_source_info": {
|
|
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
},
|
|
"data_source_detail_dict": {
|
|
"upload_file": {
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"name": "guide.txt",
|
|
"size": 2048,
|
|
"extension": "txt",
|
|
"mime_type": "text/plain",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200
|
|
}
|
|
},
|
|
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
|
|
"name": "guide.txt",
|
|
"created_from": "api",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"tokens": 512,
|
|
"indexing_status": "completed",
|
|
"error": null,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"archived": false,
|
|
"display_status": "available",
|
|
"word_count": 350,
|
|
"hit_count": 0,
|
|
"doc_form": "text_model",
|
|
"doc_metadata": [],
|
|
"summary_index_status": null,
|
|
"need_summary": false
|
|
},
|
|
"batch": "20250306150245647595"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `provider_not_initialize` : No model provider credentials are configured for the workspace.\n- `invalid_param` : The document is not available for update (only available documents can be updated).",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"too_many_files": {
|
|
"summary": "too_many_files",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "too_many_files",
|
|
"message": "Only one file is allowed."
|
|
}
|
|
},
|
|
"filename_not_exists_error": {
|
|
"summary": "filename_not_exists_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "filename_not_exists_error",
|
|
"message": "The specified filename does not exist."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"invalid_param_not_available": {
|
|
"summary": "invalid_param (not available)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Document is not available"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (vector space)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The capacity of the vector space has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Knowledge base not found.\n- `not_found` : Document not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"413": {
|
|
"description": "`file_too_large` : The uploaded file exceeds the maximum size.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"file_too_large": {
|
|
"summary": "file_too_large",
|
|
"value": {
|
|
"status": 413,
|
|
"code": "file_too_large",
|
|
"message": "File size exceeded."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"415": {
|
|
"description": "`unsupported_file_type` : The uploaded file's type is not supported.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"unsupported_file_type": {
|
|
"summary": "unsupported_file_type",
|
|
"value": {
|
|
"status": 415,
|
|
"code": "unsupported_file_type",
|
|
"message": "File type not allowed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"deprecated": true,
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/update-document-by-file",
|
|
"metadata": {
|
|
"title": "Update Document by File",
|
|
"sidebarTitle": "Update Document by File"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/download-zip": {
|
|
"post": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Download Documents as ZIP",
|
|
"description": "Downloads one or more documents as a single ZIP archive. Only documents that were uploaded as files can be included.",
|
|
"operationId": "downloadDocumentsZip",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"document_ids"
|
|
],
|
|
"properties": {
|
|
"document_ids": {
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"maxItems": 100,
|
|
"items": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document IDs to include in the archive. Get them from [List Documents](/en/api-reference/documents/list-documents)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "ZIP archive containing the requested documents.",
|
|
"content": {
|
|
"application/zip": {
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "ZIP archive binary stream."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Knowledge base API access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : You do not have permission to access this knowledge base.\n- `forbidden` : You do not have permission for one of the requested documents.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (dataset permission)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "You do not have permission to access this dataset."
|
|
}
|
|
},
|
|
"forbidden_4": {
|
|
"summary": "forbidden (document permission)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "No permission."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Document not found.\n- `not_found` : Knowledge base not found. Also returned as \"Only uploaded-file documents can be downloaded as ZIP.\" when a requested document has no uploaded file.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found_3",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Only uploaded-file documents can be downloaded as ZIP."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/download-documents-as-zip",
|
|
"metadata": {
|
|
"title": "Download Documents as ZIP",
|
|
"sidebarTitle": "Download Documents as ZIP"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/status/{action}": {
|
|
"patch": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Update Document Status in Batch",
|
|
"description": "Enables, disables, archives, or unarchives multiple documents in one request.",
|
|
"operationId": "batchUpdateDocumentStatus",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "action",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"enable",
|
|
"disable",
|
|
"archive",
|
|
"un_archive"
|
|
]
|
|
},
|
|
"description": "`enable` activates documents for retrieval, `disable` deactivates them, `archive` moves them to the archive, `un_archive` restores them from the archive."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"document_ids"
|
|
],
|
|
"properties": {
|
|
"document_ids": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Document IDs to update. Get them from [List Documents](/en/api-reference/documents/list-documents)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Documents updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"result": {
|
|
"type": "string",
|
|
"description": "Operation result."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"result": "success"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_action` : Invalid action, or a document is in a state that does not allow the action (e.g. still indexing, or not completed).",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_action": {
|
|
"summary": "invalid_action",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_action",
|
|
"message": "Invalid action."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Knowledge base API access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Knowledge base not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/documents/update-document-status-in-batch",
|
|
"metadata": {
|
|
"title": "Update Document Status in Batch",
|
|
"sidebarTitle": "Update Document Status in Batch"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/{document_id}/segments": {
|
|
"post": {
|
|
"tags": [
|
|
"Chunks"
|
|
],
|
|
"summary": "Create Chunks",
|
|
"description": "Create one or more chunks within a document.",
|
|
"operationId": "createSegments",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"segments"
|
|
],
|
|
"properties": {
|
|
"segments": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Chunk text content.",
|
|
"minLength": 1
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Answer text. Required for Q&A-mode (`qa_model`) documents."
|
|
},
|
|
"keywords": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Keywords for the chunk."
|
|
},
|
|
"attachment_ids": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Attachment file IDs."
|
|
}
|
|
},
|
|
"required": [
|
|
"content"
|
|
]
|
|
},
|
|
"description": "Array of chunk objects to create.",
|
|
"minItems": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Chunks created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of created chunks.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Segment"
|
|
}
|
|
},
|
|
"doc_form": {
|
|
"type": "string",
|
|
"description": "Document chunking mode used by this document."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
|
|
"position": 1,
|
|
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"content": "Dify is an open-source LLM app development platform.",
|
|
"sign_content": "",
|
|
"answer": "",
|
|
"word_count": 9,
|
|
"tokens": 12,
|
|
"keywords": [
|
|
"dify",
|
|
"platform",
|
|
"llm"
|
|
],
|
|
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
|
|
"index_node_hash": "abc123def456",
|
|
"hit_count": 0,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"status": "completed",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"updated_at": 1741267200,
|
|
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"indexing_at": 1741267200,
|
|
"completed_at": 1741267200,
|
|
"error": null,
|
|
"stopped_at": null,
|
|
"child_chunks": [],
|
|
"attachments": [],
|
|
"summary": null
|
|
}
|
|
],
|
|
"doc_form": "text_model"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : A chunk field is invalid (for example, `answer` is required for Q&A-mode documents) or the number of chunks exceeds the per-request limit.\n- Request-body schema validation (such as empty `content`) returns a non-standard body `{\"error\": \"<validation details>\"}` with no `code` or `status` field.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
|
|
}
|
|
},
|
|
"invalid_param_limit": {
|
|
"summary": "invalid_param (segments limit)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Exceeded maximum segments limit of 1000."
|
|
}
|
|
},
|
|
"validation_error": {
|
|
"summary": "schema validation (non-standard body)",
|
|
"value": {
|
|
"error": "1 validation error for SegmentCreatePayload\nsegments.0.content\n String should have at least 1 character [type=string_too_short, input_value='', input_type=str]"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (vector space)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The capacity of the vector space has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_4": {
|
|
"summary": "forbidden (upgrade plan)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Document is not completed.\n- `not_found` : Document is disabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document is not completed."
|
|
}
|
|
},
|
|
"not_found_4": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document is disabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chunks/create-chunks",
|
|
"metadata": {
|
|
"title": "Create Chunks",
|
|
"sidebarTitle": "Create Chunks"
|
|
}
|
|
}
|
|
},
|
|
"get": {
|
|
"tags": [
|
|
"Chunks"
|
|
],
|
|
"summary": "List Chunks",
|
|
"description": "Returns a paginated list of chunks within a document, optionally filtered by keyword or indexing status.",
|
|
"operationId": "listSegments",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
{
|
|
"name": "page",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 1,
|
|
"minimum": 1
|
|
},
|
|
"description": "Page number."
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20,
|
|
"minimum": 1
|
|
},
|
|
"description": "Number of items per page. Server caps at `100`."
|
|
},
|
|
{
|
|
"name": "status",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"style": "form",
|
|
"explode": true,
|
|
"description": "Filter chunks by indexing status, e.g. `completed`, `indexing`, `error`."
|
|
},
|
|
{
|
|
"name": "keyword",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Search keyword."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of chunks.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of chunks.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Segment"
|
|
}
|
|
},
|
|
"doc_form": {
|
|
"type": "string",
|
|
"description": "Document chunking mode used by this document."
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total number of matching chunks."
|
|
},
|
|
"has_more": {
|
|
"type": "boolean",
|
|
"description": "Whether more items exist on the next page."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Number of items per page."
|
|
},
|
|
"page": {
|
|
"type": "integer",
|
|
"description": "Current page number."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
|
|
"position": 1,
|
|
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"content": "Dify is an open-source LLM app development platform.",
|
|
"sign_content": "",
|
|
"answer": "",
|
|
"word_count": 9,
|
|
"tokens": 12,
|
|
"keywords": [
|
|
"dify",
|
|
"platform",
|
|
"llm"
|
|
],
|
|
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
|
|
"index_node_hash": "abc123def456",
|
|
"hit_count": 0,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"status": "completed",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"updated_at": 1741267200,
|
|
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"indexing_at": 1741267200,
|
|
"completed_at": 1741267200,
|
|
"error": null,
|
|
"stopped_at": null,
|
|
"child_chunks": [],
|
|
"attachments": [],
|
|
"summary": null
|
|
}
|
|
],
|
|
"doc_form": "text_model",
|
|
"total": 1,
|
|
"has_more": false,
|
|
"limit": 20,
|
|
"page": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Dataset api access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chunks/list-chunks",
|
|
"metadata": {
|
|
"title": "List Chunks",
|
|
"sidebarTitle": "List Chunks"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Chunks"
|
|
],
|
|
"summary": "Get Chunk",
|
|
"description": "Retrieve the full details of a single chunk.",
|
|
"operationId": "getSegmentDetail",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
{
|
|
"name": "segment_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Chunk details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"$ref": "#/components/schemas/Segment"
|
|
},
|
|
"doc_form": {
|
|
"type": "string",
|
|
"description": "Document chunking mode used by this document."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": {
|
|
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
|
|
"position": 1,
|
|
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"content": "Dify is an open-source LLM app development platform.",
|
|
"sign_content": "",
|
|
"answer": "",
|
|
"word_count": 9,
|
|
"tokens": 12,
|
|
"keywords": [
|
|
"dify",
|
|
"platform",
|
|
"llm"
|
|
],
|
|
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
|
|
"index_node_hash": "abc123def456",
|
|
"hit_count": 0,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"status": "completed",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"updated_at": 1741267200,
|
|
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"indexing_at": 1741267200,
|
|
"completed_at": 1741267200,
|
|
"error": null,
|
|
"stopped_at": null,
|
|
"child_chunks": [],
|
|
"attachments": [],
|
|
"summary": null
|
|
},
|
|
"doc_form": "text_model"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Dataset api access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Segment not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chunks/get-chunk",
|
|
"metadata": {
|
|
"title": "Get Chunk",
|
|
"sidebarTitle": "Get Chunk"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": [
|
|
"Chunks"
|
|
],
|
|
"summary": "Update Chunk",
|
|
"description": "Update a chunk's fields. The update re-triggers indexing for that chunk.",
|
|
"operationId": "updateSegment",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
{
|
|
"name": "segment_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"segment"
|
|
],
|
|
"properties": {
|
|
"segment": {
|
|
"type": "object",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Chunk text content."
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Answer text for Q&A-mode (`qa_model`) documents."
|
|
},
|
|
"keywords": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Keywords for the chunk."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether the chunk is enabled."
|
|
},
|
|
"regenerate_child_chunks": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Whether to regenerate child chunks."
|
|
},
|
|
"attachment_ids": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Attachment file IDs."
|
|
},
|
|
"summary": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Summary content for summary index."
|
|
}
|
|
},
|
|
"description": "Chunk data to update."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Chunk updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"$ref": "#/components/schemas/Segment"
|
|
},
|
|
"doc_form": {
|
|
"type": "string",
|
|
"description": "Document chunking mode used by this document."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": {
|
|
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
|
|
"position": 1,
|
|
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"content": "Dify is an open-source LLM app development platform.",
|
|
"sign_content": "",
|
|
"answer": "",
|
|
"word_count": 9,
|
|
"tokens": 12,
|
|
"keywords": [
|
|
"dify",
|
|
"platform",
|
|
"llm"
|
|
],
|
|
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
|
|
"index_node_hash": "abc123def456",
|
|
"hit_count": 0,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"status": "completed",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"updated_at": 1741267200,
|
|
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"indexing_at": 1741267200,
|
|
"completed_at": 1741267200,
|
|
"error": null,
|
|
"stopped_at": null,
|
|
"child_chunks": [],
|
|
"attachments": [],
|
|
"summary": null
|
|
},
|
|
"doc_form": "text_model"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : The chunk is indexing or disabled and cannot be updated, or index configuration is invalid.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
|
|
}
|
|
},
|
|
"invalid_param_state": {
|
|
"summary": "invalid_param (state)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Segment is indexing, please try again later"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (vector space)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The capacity of the vector space has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Segment not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chunks/update-chunk",
|
|
"metadata": {
|
|
"title": "Update Chunk",
|
|
"sidebarTitle": "Update Chunk"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Chunks"
|
|
],
|
|
"summary": "Delete Chunk",
|
|
"description": "Permanently delete a chunk from the document.",
|
|
"operationId": "deleteSegment",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
{
|
|
"name": "segment_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "Success."
|
|
},
|
|
"400": {
|
|
"description": "- `invalid_param` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : The chunk is already being deleted by a concurrent request.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param_model_setting": {
|
|
"summary": "invalid_param (model setting)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
|
|
}
|
|
},
|
|
"invalid_param_deleting": {
|
|
"summary": "invalid_param (deleting)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Segment is deleting."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Segment not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chunks/delete-chunk",
|
|
"metadata": {
|
|
"title": "Delete Chunk",
|
|
"sidebarTitle": "Delete Chunk"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": {
|
|
"post": {
|
|
"tags": [
|
|
"Chunks"
|
|
],
|
|
"summary": "Create Child Chunk",
|
|
"description": "Create a child chunk under a parent chunk. Intended for documents that use the parent-child (`hierarchical_model`) chunking mode.",
|
|
"operationId": "createChildChunk",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
{
|
|
"name": "segment_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"content"
|
|
],
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Child chunk text content."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Child chunk created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"$ref": "#/components/schemas/ChildChunk"
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": {
|
|
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
|
|
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
|
|
"content": "Dify is an open-source platform.",
|
|
"position": 1,
|
|
"word_count": 6,
|
|
"type": "customized",
|
|
"created_at": 1741267200,
|
|
"updated_at": 1741267200
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `provider_not_initialize` : The knowledge base uses high-quality indexing but its embedding model is missing or misconfigured.\n- `invalid_param` : Indexing the child chunk in the vector store failed; the message carries the underlying vector-store error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Vector store operation failed: [Errno 111] Connection refused"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (vector space)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The capacity of the vector space has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_4": {
|
|
"summary": "forbidden (upgrade plan)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Segment not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chunks/create-child-chunk",
|
|
"metadata": {
|
|
"title": "Create Child Chunk",
|
|
"sidebarTitle": "Create Child Chunk"
|
|
}
|
|
}
|
|
},
|
|
"get": {
|
|
"tags": [
|
|
"Chunks"
|
|
],
|
|
"summary": "List Child Chunks",
|
|
"description": "Returns a paginated list of child chunks under a specific parent chunk.",
|
|
"operationId": "getChildChunks",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
{
|
|
"name": "segment_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)."
|
|
},
|
|
{
|
|
"name": "page",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 1,
|
|
"minimum": 1
|
|
},
|
|
"description": "Page number."
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20,
|
|
"minimum": 1
|
|
},
|
|
"description": "Number of items per page. Server caps at `100`."
|
|
},
|
|
{
|
|
"name": "keyword",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Search keyword."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of child chunks.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of child chunks.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ChildChunk"
|
|
}
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total number of child chunks."
|
|
},
|
|
"total_pages": {
|
|
"type": "integer",
|
|
"description": "Total number of pages."
|
|
},
|
|
"page": {
|
|
"type": "integer",
|
|
"description": "Current page number."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Number of items per page."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
|
|
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
|
|
"content": "Dify is an open-source platform.",
|
|
"position": 1,
|
|
"word_count": 6,
|
|
"type": "customized",
|
|
"created_at": 1741267200,
|
|
"updated_at": 1741267200
|
|
}
|
|
],
|
|
"total": 1,
|
|
"total_pages": 1,
|
|
"page": 1,
|
|
"limit": 20
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Dataset api access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Segment not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chunks/list-child-chunks",
|
|
"metadata": {
|
|
"title": "List Child Chunks",
|
|
"sidebarTitle": "List Child Chunks"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": {
|
|
"patch": {
|
|
"tags": [
|
|
"Chunks"
|
|
],
|
|
"summary": "Update Child Chunk",
|
|
"description": "Update the content of an existing child chunk.",
|
|
"operationId": "updateChildChunk",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
{
|
|
"name": "segment_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)."
|
|
},
|
|
{
|
|
"name": "child_chunk_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Child chunk ID."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"content"
|
|
],
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Child chunk text content."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Child chunk updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"$ref": "#/components/schemas/ChildChunk"
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": {
|
|
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
|
|
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
|
|
"content": "Dify is an open-source platform.",
|
|
"position": 1,
|
|
"word_count": 6,
|
|
"type": "customized",
|
|
"created_at": 1741267200,
|
|
"updated_at": 1741267200
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : Re-indexing the child chunk in the vector store failed; the message carries the underlying vector-store error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Vector store operation failed: [Errno 111] Connection refused"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : The capacity of the vector space has reached the limit of your subscription.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (vector space)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "The capacity of the vector space has reached the limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_4": {
|
|
"summary": "forbidden (upgrade plan)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.\n- `not_found` : Child chunk not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Segment not found."
|
|
}
|
|
},
|
|
"not_found_4": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Child chunk not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chunks/update-child-chunk",
|
|
"metadata": {
|
|
"title": "Update Child Chunk",
|
|
"sidebarTitle": "Update Child Chunk"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Chunks"
|
|
],
|
|
"summary": "Delete Child Chunk",
|
|
"description": "Permanently delete a child chunk from its parent chunk.",
|
|
"operationId": "deleteChildChunk",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
{
|
|
"name": "segment_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Parent chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks)."
|
|
},
|
|
{
|
|
"name": "child_chunk_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Child chunk ID."
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "Success."
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : Removing the child chunk index from the vector store failed; the message carries the underlying vector-store error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Vector store operation failed: [Errno 111] Connection refused"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
},
|
|
"forbidden_3": {
|
|
"summary": "forbidden (upgrade plan)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "- `not_found` : Dataset not found.\n- `not_found` : Document not found.\n- `not_found` : Segment not found.\n- `not_found` : Child chunk not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found_1": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
},
|
|
"not_found_2": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Document not found."
|
|
}
|
|
},
|
|
"not_found_3": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Segment not found."
|
|
}
|
|
},
|
|
"not_found_4": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Child chunk not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/chunks/delete-child-chunk",
|
|
"metadata": {
|
|
"title": "Delete Child Chunk",
|
|
"sidebarTitle": "Delete Child Chunk"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/retrieve": {
|
|
"post": {
|
|
"tags": [
|
|
"Knowledge Bases"
|
|
],
|
|
"summary": "Retrieve Chunks from a Knowledge Base / Test Retrieval",
|
|
"description": "Searches a knowledge base and returns the chunks most relevant to the query, for both production retrieval and test retrieval.",
|
|
"operationId": "retrieveSegments",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"query"
|
|
],
|
|
"properties": {
|
|
"query": {
|
|
"type": "string",
|
|
"maxLength": 250,
|
|
"description": "Search query text."
|
|
},
|
|
"retrieval_model": {
|
|
"$ref": "#/components/schemas/RetrievalModel",
|
|
"description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base."
|
|
},
|
|
"attachment_ids": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"nullable": true,
|
|
"description": "List of attachment IDs to include in the retrieval context."
|
|
},
|
|
"external_retrieval_model": {
|
|
"type": "object",
|
|
"description": "Retrieval settings for external knowledge bases.",
|
|
"properties": {
|
|
"top_k": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results to return."
|
|
},
|
|
"score_threshold": {
|
|
"type": "number",
|
|
"description": "Minimum similarity score threshold for filtering results."
|
|
},
|
|
"score_threshold_enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether score threshold filtering is enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Retrieval results.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"query": {
|
|
"type": "object",
|
|
"description": "The original query object.",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "The query text."
|
|
}
|
|
}
|
|
},
|
|
"records": {
|
|
"type": "array",
|
|
"description": "List of matched retrieval records.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"segment": {
|
|
"type": "object",
|
|
"description": "Matched chunk from the knowledge base.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier of the chunk."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Position of the chunk within the document."
|
|
},
|
|
"document_id": {
|
|
"type": "string",
|
|
"description": "ID of the document this chunk belongs to."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Text content of the chunk."
|
|
},
|
|
"sign_content": {
|
|
"type": "string",
|
|
"description": "Signed content hash for integrity verification."
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Answer content, used in Q&A mode documents."
|
|
},
|
|
"word_count": {
|
|
"type": "integer",
|
|
"description": "Word count of the chunk content."
|
|
},
|
|
"tokens": {
|
|
"type": "integer",
|
|
"description": "Token count of the chunk content."
|
|
},
|
|
"keywords": {
|
|
"type": "array",
|
|
"description": "Keywords associated with this chunk for keyword-based retrieval.",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"index_node_id": {
|
|
"type": "string",
|
|
"description": "ID of the index node in the vector store."
|
|
},
|
|
"index_node_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the indexed content, used to detect changes."
|
|
},
|
|
"hit_count": {
|
|
"type": "integer",
|
|
"description": "Number of times this chunk has been matched in retrieval queries."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether the chunk is enabled for retrieval."
|
|
},
|
|
"disabled_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when the chunk was disabled. `null` if enabled."
|
|
},
|
|
"disabled_by": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the user who disabled the chunk. `null` if enabled."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Indexing status of the chunk."
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "ID of the user who created the chunk."
|
|
},
|
|
"created_at": {
|
|
"type": "number",
|
|
"description": "Creation timestamp (Unix epoch in seconds)."
|
|
},
|
|
"indexing_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when indexing started. `null` if not yet started."
|
|
},
|
|
"completed_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when indexing completed. `null` if not yet completed."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if indexing failed. `null` when no error."
|
|
},
|
|
"stopped_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when indexing was stopped. `null` if not stopped."
|
|
},
|
|
"document": {
|
|
"type": "object",
|
|
"description": "Parent document information for the matched chunk.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier of the document."
|
|
},
|
|
"data_source_type": {
|
|
"type": "string",
|
|
"description": "How the document was created."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Document name."
|
|
},
|
|
"doc_type": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Document type classification. `null` if not set."
|
|
},
|
|
"doc_metadata": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Metadata values for the document. `null` if no metadata is configured."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"child_chunks": {
|
|
"type": "array",
|
|
"description": "Matched child chunks within the chunk, if using hierarchical indexing.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier of the child chunk."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Text content of the child chunk."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Position of the child chunk within the parent chunk."
|
|
},
|
|
"score": {
|
|
"type": "number",
|
|
"description": "Similarity score of the child chunk."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"score": {
|
|
"type": "number",
|
|
"description": "Similarity score."
|
|
},
|
|
"tsne_position": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "t-SNE visualization position."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"description": "Files attached to this chunk.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Attachment file identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Original file name."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "File size in bytes."
|
|
},
|
|
"extension": {
|
|
"type": "string",
|
|
"description": "File extension."
|
|
},
|
|
"mime_type": {
|
|
"type": "string",
|
|
"description": "MIME type of the file."
|
|
},
|
|
"source_url": {
|
|
"type": "string",
|
|
"description": "URL to access the attachment."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"summary": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Summary content if retrieved via summary index."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"query": {
|
|
"content": "What is Dify?"
|
|
},
|
|
"records": [
|
|
{
|
|
"segment": {
|
|
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
|
|
"position": 1,
|
|
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"content": "Dify is an open-source LLM app development platform.",
|
|
"sign_content": "",
|
|
"answer": "",
|
|
"word_count": 9,
|
|
"tokens": 12,
|
|
"keywords": [
|
|
"dify",
|
|
"platform",
|
|
"llm"
|
|
],
|
|
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
|
|
"index_node_hash": "abc123def456",
|
|
"hit_count": 1,
|
|
"enabled": true,
|
|
"disabled_at": null,
|
|
"disabled_by": null,
|
|
"status": "completed",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": 1741267200,
|
|
"indexing_at": 1741267200,
|
|
"completed_at": 1741267200,
|
|
"error": null,
|
|
"stopped_at": null,
|
|
"document": {
|
|
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
|
|
"data_source_type": "upload_file",
|
|
"name": "guide.txt",
|
|
"doc_type": null,
|
|
"doc_metadata": null
|
|
}
|
|
},
|
|
"child_chunks": [],
|
|
"score": 0.92,
|
|
"tsne_position": null,
|
|
"files": [],
|
|
"summary": null
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `dataset_not_initialized` : The knowledge base is still initializing or indexing.\n- `provider_not_initialize` : The model provider has no valid credentials configured.\n- `provider_quota_exceeded` : The Dify-hosted model provider quota is exhausted.\n- `model_currently_not_support` : The selected model is not currently supported.\n- `completion_request_error` : The model request failed.\n- `invalid_param` : A request parameter is invalid.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"dataset_not_initialized": {
|
|
"summary": "dataset_not_initialized",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "dataset_not_initialized",
|
|
"message": "The dataset is still being initialized or indexing. Please wait a moment."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"provider_quota_exceeded": {
|
|
"summary": "provider_quota_exceeded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_quota_exceeded",
|
|
"message": "Your quota for Dify Hosted Model Provider has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
|
|
}
|
|
},
|
|
"model_currently_not_support": {
|
|
"summary": "model_currently_not_support",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "model_currently_not_support",
|
|
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
|
|
}
|
|
},
|
|
"completion_request_error": {
|
|
"summary": "completion_request_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "completion_request_error",
|
|
"message": "Completion request failed."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Invalid parameter value."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : API access is not enabled for this knowledge base.\n- `forbidden` : Your subscription's knowledge base request rate limit has been reached.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : No knowledge base matches `dataset_id`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`internal_server_error` : An internal error occurred during retrieval.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"internal_server_error": {
|
|
"summary": "internal_server_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "internal_server_error",
|
|
"message": "An internal error occurred."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval",
|
|
"metadata": {
|
|
"title": "Retrieve Chunks from a Knowledge Base / Test Retrieval",
|
|
"sidebarTitle": "Retrieve Chunks from a Knowledge Base / Test Retrieval"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/tags": {
|
|
"post": {
|
|
"tags": [
|
|
"Tags"
|
|
],
|
|
"summary": "Create Knowledge Tag",
|
|
"description": "Create a tag for organizing knowledge bases.",
|
|
"operationId": "createKnowledgeTag",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"name"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"maxLength": 50,
|
|
"description": "Tag name. Must be unique within the workspace."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Tag created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Tag identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Tag display name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Tag type. Always `knowledge` for knowledge base tags."
|
|
},
|
|
"binding_count": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Number of knowledge bases bound to this tag."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
|
|
"name": "Product Docs",
|
|
"type": "knowledge",
|
|
"binding_count": "0"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : A knowledge tag with the same name already exists.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Tag name already exists"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/tags/create-knowledge-tag",
|
|
"metadata": {
|
|
"title": "Create Knowledge Tag",
|
|
"sidebarTitle": "Create Knowledge Tag"
|
|
}
|
|
}
|
|
},
|
|
"get": {
|
|
"tags": [
|
|
"Tags"
|
|
],
|
|
"summary": "List Knowledge Tags",
|
|
"description": "Returns all knowledge base tags in the workspace.",
|
|
"operationId": "getKnowledgeTags",
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of tags.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Tag identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Tag display name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Tag type. Always `knowledge` for knowledge base tags."
|
|
},
|
|
"binding_count": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Number of knowledge bases bound to this tag."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": [
|
|
{
|
|
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
|
|
"name": "Product Docs",
|
|
"type": "knowledge",
|
|
"binding_count": "0"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/tags/list-knowledge-tags",
|
|
"metadata": {
|
|
"title": "List Knowledge Tags",
|
|
"sidebarTitle": "List Knowledge Tags"
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"tags": [
|
|
"Tags"
|
|
],
|
|
"summary": "Update Knowledge Tag",
|
|
"description": "Rename a knowledge base tag.",
|
|
"operationId": "updateKnowledgeTag",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"tag_id",
|
|
"name"
|
|
],
|
|
"properties": {
|
|
"tag_id": {
|
|
"type": "string",
|
|
"description": "ID of the tag to rename. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags)."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"maxLength": 50,
|
|
"description": "New name for the tag. Must be unique within the workspace."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Tag updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Tag identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Tag display name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Tag type. Always `knowledge` for knowledge base tags."
|
|
},
|
|
"binding_count": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Number of knowledge bases bound to this tag."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
|
|
"name": "Product Docs",
|
|
"type": "knowledge",
|
|
"binding_count": "0"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : A knowledge tag with the same name already exists.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Tag name already exists"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : The specified tag does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Tag not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/tags/update-knowledge-tag",
|
|
"metadata": {
|
|
"title": "Update Knowledge Tag",
|
|
"sidebarTitle": "Update Knowledge Tag"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Tags"
|
|
],
|
|
"summary": "Delete Knowledge Tag",
|
|
"description": "Permanently delete a knowledge base tag. Does not delete the knowledge bases that were tagged.",
|
|
"operationId": "deleteKnowledgeTag",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"tag_id"
|
|
],
|
|
"properties": {
|
|
"tag_id": {
|
|
"type": "string",
|
|
"description": "ID of the tag to delete. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"204": {
|
|
"description": "Success."
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : The specified tag does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Tag not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/tags/delete-knowledge-tag",
|
|
"metadata": {
|
|
"title": "Delete Knowledge Tag",
|
|
"sidebarTitle": "Delete Knowledge Tag"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/tags/binding": {
|
|
"post": {
|
|
"tags": [
|
|
"Tags"
|
|
],
|
|
"summary": "Create Tag Binding",
|
|
"description": "Bind one or more tags to a knowledge base. A knowledge base can have multiple tags.",
|
|
"operationId": "bindTagsToDataset",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"tag_ids",
|
|
"target_id"
|
|
],
|
|
"properties": {
|
|
"tag_ids": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"minItems": 1,
|
|
"description": "IDs of the tags to bind. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags). Unknown tag IDs are silently ignored."
|
|
},
|
|
"target_id": {
|
|
"type": "string",
|
|
"description": "Knowledge base to bind the tags to. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"204": {
|
|
"description": "Success."
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : The target knowledge base does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/tags/create-tag-binding",
|
|
"metadata": {
|
|
"title": "Create Tag Binding",
|
|
"sidebarTitle": "Create Tag Binding"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/tags/unbinding": {
|
|
"post": {
|
|
"tags": [
|
|
"Tags"
|
|
],
|
|
"summary": "Delete Tag Binding",
|
|
"description": "Remove one or more tags from a knowledge base.",
|
|
"operationId": "unbindTagFromDataset",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"target_id"
|
|
],
|
|
"properties": {
|
|
"tag_ids": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"minItems": 1,
|
|
"description": "Tag IDs to unbind. Required unless the legacy `tag_id` is provided. See [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags)."
|
|
},
|
|
"tag_id": {
|
|
"type": "string",
|
|
"deprecated": true,
|
|
"description": "Legacy single-tag form. Normalized into `tag_ids` server-side. Use `tag_ids` for new integrations."
|
|
},
|
|
"target_id": {
|
|
"type": "string",
|
|
"description": "Knowledge base to unbind the tags from. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"204": {
|
|
"description": "Success."
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : The target knowledge base does not exist.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/tags/delete-tag-binding",
|
|
"metadata": {
|
|
"title": "Delete Tag Binding",
|
|
"sidebarTitle": "Delete Tag Binding"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/tags": {
|
|
"get": {
|
|
"tags": [
|
|
"Tags"
|
|
],
|
|
"summary": "Get Knowledge Base Tags",
|
|
"description": "Returns the tags bound to a knowledge base.",
|
|
"operationId": "queryDatasetTags",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Tags bound to the knowledge base.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of tags bound to this knowledge base.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Tag identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Tag display name."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total number of tags bound to this knowledge base."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
|
|
"name": "Product Docs"
|
|
}
|
|
],
|
|
"total": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Dataset api access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Dataset not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/tags/get-knowledge-base-tags",
|
|
"metadata": {
|
|
"title": "Get Knowledge Base Tags",
|
|
"sidebarTitle": "Get Knowledge Base Tags"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/metadata": {
|
|
"post": {
|
|
"tags": [
|
|
"Metadata"
|
|
],
|
|
"summary": "Create Metadata Field",
|
|
"description": "Create a custom metadata field for annotating documents in the knowledge base with structured information.",
|
|
"operationId": "createMetadataField",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"type",
|
|
"name"
|
|
],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"string",
|
|
"number",
|
|
"time"
|
|
],
|
|
"description": "`string` for text values, `number` for numeric values, `time` for date/time values."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Name for the metadata field. Must be unique among the knowledge base's fields and at most 255 characters."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Metadata field created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Metadata field identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Metadata field name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Metadata field type."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
|
|
"name": "author",
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The metadata name already exists, exceeds 255 characters, or conflicts with a built-in field.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Metadata name already exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Dataset not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/metadata/create-metadata-field",
|
|
"metadata": {
|
|
"title": "Create Metadata Field",
|
|
"sidebarTitle": "Create Metadata Field"
|
|
}
|
|
}
|
|
},
|
|
"get": {
|
|
"tags": [
|
|
"Metadata"
|
|
],
|
|
"summary": "List Metadata Fields",
|
|
"description": "Returns all metadata fields for the knowledge base, both custom and built-in, with the count of documents using each field.",
|
|
"operationId": "listMetadataFields",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Metadata fields for the knowledge base.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"doc_metadata": {
|
|
"type": "array",
|
|
"description": "List of metadata field definitions.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Metadata field identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Metadata field name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Metadata field type."
|
|
},
|
|
"count": {
|
|
"type": "integer",
|
|
"description": "Number of documents using this metadata field."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"built_in_field_enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether built-in metadata fields are enabled for this knowledge base."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"doc_metadata": [
|
|
{
|
|
"id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
|
|
"name": "author",
|
|
"type": "string",
|
|
"count": 3
|
|
}
|
|
],
|
|
"built_in_field_enabled": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Dataset api access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Dataset not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/metadata/list-metadata-fields",
|
|
"metadata": {
|
|
"title": "List Metadata Fields",
|
|
"sidebarTitle": "List Metadata Fields"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/metadata/{metadata_id}": {
|
|
"patch": {
|
|
"tags": [
|
|
"Metadata"
|
|
],
|
|
"summary": "Update Metadata Field",
|
|
"description": "Rename a custom metadata field.",
|
|
"operationId": "updateMetadataField",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "metadata_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "ID of the metadata field to rename. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"name"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "New name for the field. Must be unique among the knowledge base's fields and at most 255 characters."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Metadata field updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Metadata field identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Metadata field name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Metadata field type."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
|
|
"name": "author",
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The metadata name already exists, exceeds 255 characters, or conflicts with a built-in field.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Metadata name already exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Dataset not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/metadata/update-metadata-field",
|
|
"metadata": {
|
|
"title": "Update Metadata Field",
|
|
"sidebarTitle": "Update Metadata Field"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Metadata"
|
|
],
|
|
"summary": "Delete Metadata Field",
|
|
"description": "Permanently delete a custom metadata field. Documents that used the field lose their values for it.",
|
|
"operationId": "deleteMetadataField",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "metadata_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "ID of the metadata field to delete. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "Success."
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Dataset not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/metadata/delete-metadata-field",
|
|
"metadata": {
|
|
"title": "Delete Metadata Field",
|
|
"sidebarTitle": "Delete Metadata Field"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/metadata/built-in": {
|
|
"get": {
|
|
"tags": [
|
|
"Metadata"
|
|
],
|
|
"summary": "Get Built-in Metadata Fields",
|
|
"description": "Returns the built-in metadata fields provided by the system.",
|
|
"operationId": "getBuiltInMetadataFields",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Built-in metadata fields.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"fields": {
|
|
"type": "array",
|
|
"description": "List of system-provided metadata fields.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Built-in field identifier. `document_name` for the document title, `uploader` for the creator, `upload_date` for creation time, `last_update_date` for last modification time, `source` for the document origin."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Field data type. `string` for text values, `time` for date/time values."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"fields": [
|
|
{
|
|
"name": "document_name",
|
|
"type": "string"
|
|
},
|
|
{
|
|
"name": "uploader",
|
|
"type": "string"
|
|
},
|
|
{
|
|
"name": "upload_date",
|
|
"type": "time"
|
|
},
|
|
{
|
|
"name": "last_update_date",
|
|
"type": "time"
|
|
},
|
|
{
|
|
"name": "source",
|
|
"type": "string"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : Dataset api access is not enabled.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Dataset not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/metadata/get-built-in-metadata-fields",
|
|
"metadata": {
|
|
"title": "Get Built-in Metadata Fields",
|
|
"sidebarTitle": "Get Built-in Metadata Fields"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/metadata/built-in/{action}": {
|
|
"post": {
|
|
"tags": [
|
|
"Metadata"
|
|
],
|
|
"summary": "Update Built-in Metadata Field",
|
|
"description": "Enable or disable built-in metadata fields for the knowledge base.",
|
|
"operationId": "toggleBuiltInMetadataField",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "action",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"enable",
|
|
"disable"
|
|
]
|
|
},
|
|
"description": "`enable` to activate built-in metadata fields, `disable` to deactivate them."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Built-in metadata field toggled successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"result": {
|
|
"type": "string",
|
|
"description": "Operation result."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"result": "success"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Dataset not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/metadata/update-built-in-metadata-field",
|
|
"metadata": {
|
|
"title": "Update Built-in Metadata Field",
|
|
"sidebarTitle": "Update Built-in Metadata Field"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/documents/metadata": {
|
|
"post": {
|
|
"tags": [
|
|
"Metadata"
|
|
],
|
|
"summary": "Update Document Metadata in Batch",
|
|
"description": "Update metadata values for multiple documents in a single request.",
|
|
"operationId": "batchUpdateDocumentMetadata",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID. See [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"operation_data"
|
|
],
|
|
"properties": {
|
|
"operation_data": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": [
|
|
"document_id",
|
|
"metadata_list"
|
|
],
|
|
"properties": {
|
|
"document_id": {
|
|
"type": "string",
|
|
"description": "ID of the document to update. See [List Documents](/en/api-reference/documents/list-documents)."
|
|
},
|
|
"metadata_list": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"name"
|
|
],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Metadata field ID. See [List Metadata Fields](/en/api-reference/metadata/list-metadata-fields)."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Metadata field name."
|
|
},
|
|
"value": {
|
|
"description": "Metadata value. Can be a string, number, or `null`."
|
|
}
|
|
}
|
|
},
|
|
"description": "Metadata fields to set on the document."
|
|
},
|
|
"partial_update": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Whether to partially update metadata, keeping existing values for unspecified fields."
|
|
}
|
|
}
|
|
},
|
|
"description": "Document metadata update operations, one entry per document."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document metadata updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"result": {
|
|
"type": "string",
|
|
"description": "Operation result."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"result": "success"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : A referenced document was not found, or another metadata operation is already running for a document in this request.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param_doc": {
|
|
"summary": "invalid_param (document)",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Document not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "- `forbidden` : Dataset api access is not enabled.\n- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden_1": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
},
|
|
"forbidden_2": {
|
|
"summary": "forbidden (rate limit)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : Dataset not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/metadata/update-document-metadata-in-batch",
|
|
"metadata": {
|
|
"title": "Update Document Metadata in Batch",
|
|
"sidebarTitle": "Update Document Metadata in Batch"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workspaces/current/models/model-types/{model_type}": {
|
|
"get": {
|
|
"tags": [
|
|
"Models"
|
|
],
|
|
"summary": "Get Available Models",
|
|
"description": "Returns the available models of a given type. Use it to find the `text-embedding` and `rerank` models to configure on a knowledge base.",
|
|
"operationId": "getAvailableModels",
|
|
"parameters": [
|
|
{
|
|
"name": "model_type",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"text-embedding",
|
|
"rerank",
|
|
"llm",
|
|
"tts",
|
|
"speech2text",
|
|
"moderation"
|
|
]
|
|
},
|
|
"description": "Type of model to retrieve. For knowledge base configuration, use `text-embedding` for embedding models or `rerank` for reranking models."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Available models for the specified type.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of model providers with their available models.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"provider": {
|
|
"type": "string",
|
|
"description": "Model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). Legacy providers may return the bare short form (e.g. `openai`)."
|
|
},
|
|
"label": {
|
|
"type": "object",
|
|
"description": "Localized display name of the provider.",
|
|
"properties": {
|
|
"en_US": {
|
|
"type": "string",
|
|
"description": "English display name."
|
|
},
|
|
"zh_Hans": {
|
|
"type": "string",
|
|
"description": "Chinese display name."
|
|
}
|
|
}
|
|
},
|
|
"icon_small": {
|
|
"type": "object",
|
|
"description": "URL of the provider's small icon.",
|
|
"properties": {
|
|
"en_US": {
|
|
"type": "string",
|
|
"description": "Small icon URL."
|
|
},
|
|
"zh_Hans": {
|
|
"type": "string",
|
|
"description": "Chinese icon URL."
|
|
}
|
|
}
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Provider status. `active` when credentials are configured and valid."
|
|
},
|
|
"models": {
|
|
"type": "array",
|
|
"description": "List of available models from this provider.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"model": {
|
|
"type": "string",
|
|
"description": "Model identifier. Use this as the `embedding_model` value when creating or updating a knowledge base."
|
|
},
|
|
"label": {
|
|
"type": "object",
|
|
"description": "Localized display name of the model.",
|
|
"properties": {
|
|
"en_US": {
|
|
"type": "string",
|
|
"description": "English model name."
|
|
},
|
|
"zh_Hans": {
|
|
"type": "string",
|
|
"description": "Chinese model name."
|
|
}
|
|
}
|
|
},
|
|
"model_type": {
|
|
"type": "string",
|
|
"description": "Type of the model, matching the `model_type` path parameter."
|
|
},
|
|
"features": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"description": "Supported features of the model, `null` if none.",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"fetch_from": {
|
|
"type": "string",
|
|
"description": "Where the model definition comes from. `predefined-model` for built-in models, `customizable-model` for user-configured models."
|
|
},
|
|
"model_properties": {
|
|
"type": "object",
|
|
"description": "Model-specific properties such as `context_size`."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Model availability status. `active` when ready to use."
|
|
},
|
|
"deprecated": {
|
|
"type": "boolean",
|
|
"description": "Whether the model is deprecated."
|
|
},
|
|
"load_balancing_enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether load balancing is enabled for the model."
|
|
},
|
|
"has_invalid_load_balancing_configs": {
|
|
"type": "boolean",
|
|
"description": "Whether the model has invalid load-balancing configurations."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"tenant_id": {
|
|
"type": "string",
|
|
"description": "Workspace ID the provider configuration belongs to."
|
|
},
|
|
"icon_small_dark": {
|
|
"type": "object",
|
|
"description": "Dark-mode icon URLs; `null` when the provider has none.",
|
|
"properties": {
|
|
"en_US": {
|
|
"type": "string"
|
|
},
|
|
"zh_Hans": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"data": [
|
|
{
|
|
"provider": "langgenius/openai/openai",
|
|
"label": {
|
|
"en_US": "OpenAI",
|
|
"zh_Hans": "OpenAI"
|
|
},
|
|
"icon_small": {
|
|
"en_US": "https://example.com/openai-small.svg",
|
|
"zh_Hans": "https://example.com/openai-small.svg"
|
|
},
|
|
"status": "active",
|
|
"models": [
|
|
{
|
|
"model": "text-embedding-3-small",
|
|
"label": {
|
|
"en_US": "text-embedding-3-small",
|
|
"zh_Hans": "text-embedding-3-small"
|
|
},
|
|
"model_type": "text-embedding",
|
|
"features": null,
|
|
"fetch_from": "predefined-model",
|
|
"model_properties": {
|
|
"context_size": 8191
|
|
},
|
|
"status": "active",
|
|
"deprecated": false,
|
|
"load_balancing_enabled": false,
|
|
"has_invalid_load_balancing_configs": false
|
|
}
|
|
],
|
|
"tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
|
|
"icon_small_dark": null
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/models/get-available-models",
|
|
"metadata": {
|
|
"title": "Get Available Models",
|
|
"sidebarTitle": "Get Available Models"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/pipeline/file-upload": {
|
|
"post": {
|
|
"tags": [
|
|
"Knowledge Pipeline"
|
|
],
|
|
"summary": "Upload Pipeline File",
|
|
"description": "Uploads a file for use in a knowledge pipeline. Use the returned `id` as the `reference` of a `local_file` item in [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline).",
|
|
"operationId": "uploadPipelineFile",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"file"
|
|
],
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "The file to upload, as one `multipart/form-data` part."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "File uploaded successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier of the uploaded file."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Original file name."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "File size in bytes."
|
|
},
|
|
"extension": {
|
|
"type": "string",
|
|
"description": "File extension."
|
|
},
|
|
"mime_type": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "MIME type of the file. May be `null` if the upload did not include one."
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "ID of the user who uploaded the file."
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Upload timestamp in ISO 8601 format. May be `null` while the record is being created."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"name": "report.pdf",
|
|
"size": 524288,
|
|
"extension": "pdf",
|
|
"mime_type": "application/pdf",
|
|
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
|
|
"created_at": "2025-03-06T12:00:00"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `no_file_uploaded` : No file was provided in the request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `too_many_files` : Only one file is allowed per request.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"no_file_uploaded": {
|
|
"summary": "no_file_uploaded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "no_file_uploaded",
|
|
"message": "Please upload your file."
|
|
}
|
|
},
|
|
"filename_not_exists_error": {
|
|
"summary": "filename_not_exists_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "filename_not_exists_error",
|
|
"message": "The specified filename does not exist."
|
|
}
|
|
},
|
|
"too_many_files": {
|
|
"summary": "too_many_files",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "too_many_files",
|
|
"message": "Only one file is allowed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"413": {
|
|
"description": "`file_too_large` : The file exceeds the upload size limit.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"file_too_large": {
|
|
"summary": "file_too_large",
|
|
"value": {
|
|
"status": 413,
|
|
"code": "file_too_large",
|
|
"message": "File size exceeded."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"415": {
|
|
"description": "`unsupported_file_type` : The file type is not supported.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"unsupported_file_type": {
|
|
"summary": "unsupported_file_type",
|
|
"value": {
|
|
"status": 415,
|
|
"code": "unsupported_file_type",
|
|
"message": "File type not allowed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-pipeline/upload-pipeline-file",
|
|
"metadata": {
|
|
"title": "Upload Pipeline File",
|
|
"sidebarTitle": "Upload Pipeline File"
|
|
}
|
|
},
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/pipeline/file-upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf'"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/pipeline/datasource-plugins": {
|
|
"get": {
|
|
"tags": [
|
|
"Knowledge Pipeline"
|
|
],
|
|
"summary": "List Datasource Plugins",
|
|
"description": "Returns the datasource nodes configured in the knowledge pipeline, each with the plugin it uses and the metadata needed to run it.",
|
|
"operationId": "listDatasourcePlugins",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "is_published",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "boolean",
|
|
"default": true
|
|
},
|
|
"description": "Whether to read nodes from the published pipeline version rather than the draft."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of datasource nodes configured in the pipeline.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "ID of the datasource node in the pipeline workflow. Pass this as `node_id` to [Run Datasource Node](/en/api-reference/knowledge-pipeline/run-datasource-node), or as `start_node_id` to [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline)."
|
|
},
|
|
"plugin_id": {
|
|
"type": "string",
|
|
"description": "ID of the datasource plugin providing this node."
|
|
},
|
|
"provider_name": {
|
|
"type": "string",
|
|
"description": "Provider name registered by the datasource plugin."
|
|
},
|
|
"datasource_type": {
|
|
"type": "string",
|
|
"description": "Type of datasource. One of `local_file`, `online_document`, `online_drive`, `website_crawl`."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Display title configured for the node."
|
|
},
|
|
"user_input_variables": {
|
|
"type": "array",
|
|
"description": "Pipeline input variables the caller must supply for this datasource, derived from `{{#...#}}` references in the node's datasource parameters. Each item follows the pipeline variable schema used by the workflow.",
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
}
|
|
},
|
|
"credentials": {
|
|
"type": "array",
|
|
"description": "Credentials available for authenticating with this datasource.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Credential ID. Pass this as `credential_id` to [Run Datasource Node](/en/api-reference/knowledge-pipeline/run-datasource-node) or in per-item `credential_id` fields of [Run Pipeline](/en/api-reference/knowledge-pipeline/run-pipeline)."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Display name of the credential."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Credential type defined by the datasource plugin."
|
|
},
|
|
"is_default": {
|
|
"type": "boolean",
|
|
"description": "Whether this credential is the default for the provider."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": [
|
|
{
|
|
"node_id": "1719288585006",
|
|
"plugin_id": "langgenius/notion_datasource",
|
|
"provider_name": "notion",
|
|
"datasource_type": "online_document",
|
|
"title": "Notion Documents",
|
|
"user_input_variables": [],
|
|
"credentials": [
|
|
{
|
|
"id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
|
|
"name": "Production Notion",
|
|
"type": "api-key",
|
|
"is_default": true
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The knowledge base has no processing pipeline configured.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Pipeline not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : API access is not enabled for this knowledge base.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : No knowledge base matches `dataset_id`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-pipeline/list-datasource-plugins",
|
|
"metadata": {
|
|
"title": "List Datasource Plugins",
|
|
"sidebarTitle": "List Datasource Plugins"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": {
|
|
"post": {
|
|
"tags": [
|
|
"Knowledge Pipeline"
|
|
],
|
|
"summary": "Run Datasource Node",
|
|
"description": "Runs a single datasource node in the knowledge pipeline and streams its execution events.",
|
|
"operationId": "runDatasourceNode",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
},
|
|
{
|
|
"name": "node_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "ID of the datasource node to run, from [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"inputs",
|
|
"datasource_type",
|
|
"is_published"
|
|
],
|
|
"properties": {
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Input variables for the datasource node."
|
|
},
|
|
"datasource_type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"online_document",
|
|
"local_file",
|
|
"website_crawl",
|
|
"online_drive"
|
|
],
|
|
"description": "Type of the datasource."
|
|
},
|
|
"credential_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the credential to authenticate with the datasource, from the `credentials` array of [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins)."
|
|
},
|
|
"is_published": {
|
|
"type": "boolean",
|
|
"description": "Whether to run the published version of the node instead of the draft."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Streaming response with node execution events.",
|
|
"content": {
|
|
"text/event-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Server-Sent Events stream of node execution progress and results. See [SSE Streaming](/en/api-reference/guides/streaming) for parsing."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The knowledge base has no processing pipeline configured, or the request body failed validation.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Pipeline not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : API access is not enabled for this knowledge base.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : No knowledge base matches `dataset_id`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-pipeline/run-datasource-node",
|
|
"metadata": {
|
|
"title": "Run Datasource Node",
|
|
"sidebarTitle": "Run Datasource Node"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/datasets/{dataset_id}/pipeline/run": {
|
|
"post": {
|
|
"tags": [
|
|
"Knowledge Pipeline"
|
|
],
|
|
"summary": "Run Pipeline",
|
|
"description": "Runs the full knowledge pipeline over one or more datasources. `response_mode` selects a streaming or blocking response.",
|
|
"operationId": "runPipeline",
|
|
"parameters": [
|
|
{
|
|
"name": "dataset_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"inputs",
|
|
"datasource_type",
|
|
"datasource_info_list",
|
|
"start_node_id",
|
|
"is_published",
|
|
"response_mode"
|
|
],
|
|
"properties": {
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Key-value pairs for pipeline input variables defined in the workflow. Pass `{}` if the pipeline has no input variables."
|
|
},
|
|
"datasource_type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"local_file",
|
|
"online_document",
|
|
"website_crawl",
|
|
"online_drive"
|
|
],
|
|
"description": "Type of the datasource. Determines which fields are expected in `datasource_info_list` items."
|
|
},
|
|
"datasource_info_list": {
|
|
"type": "array",
|
|
"description": "List of datasource objects to process. The expected item structure depends on `datasource_type`.",
|
|
"items": {
|
|
"oneOf": [
|
|
{
|
|
"title": "Local File",
|
|
"type": "object",
|
|
"required": [
|
|
"reference"
|
|
],
|
|
"properties": {
|
|
"reference": {
|
|
"type": "string",
|
|
"description": "Use the `id` returned by the [Upload Pipeline File](/en/api-reference/knowledge-pipeline/upload-pipeline-file) endpoint. `related_id` is accepted as an alias."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Document title. Defaults to `\"untitled\"`."
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"title": "Online Document",
|
|
"type": "object",
|
|
"required": [
|
|
"workspace_id",
|
|
"page"
|
|
],
|
|
"properties": {
|
|
"workspace_id": {
|
|
"type": "string",
|
|
"description": "ID of the workspace or database in the external platform (e.g., a Notion workspace ID)."
|
|
},
|
|
"page": {
|
|
"type": "object",
|
|
"description": "Page details.",
|
|
"required": [
|
|
"page_id",
|
|
"type"
|
|
],
|
|
"properties": {
|
|
"page_id": {
|
|
"type": "string",
|
|
"description": "Page identifier."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Page type defined by the datasource plugin (e.g., `\"page\"`, `\"database\"`)."
|
|
},
|
|
"page_name": {
|
|
"type": "string",
|
|
"description": "Display name. Defaults to `\"untitled\"`."
|
|
}
|
|
}
|
|
},
|
|
"credential_id": {
|
|
"type": "string",
|
|
"description": "Credential for authenticating with the external platform. Managed via the Dify console. If omitted, the provider's default credential is used."
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"title": "Website Crawl",
|
|
"type": "object",
|
|
"required": [
|
|
"url"
|
|
],
|
|
"properties": {
|
|
"url": {
|
|
"type": "string",
|
|
"description": "URL to crawl."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Used as the document name. Defaults to `\"untitled\"`."
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"title": "Online Drive",
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"type"
|
|
],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "File or folder ID."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"file",
|
|
"folder"
|
|
],
|
|
"description": "Whether this entry is a single file or a folder to expand."
|
|
},
|
|
"bucket": {
|
|
"type": "string",
|
|
"description": "Storage bucket name. Required by some drive providers (e.g., S3-compatible stores); omit if the provider does not use buckets."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "File name. Defaults to `\"untitled\"`."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"start_node_id": {
|
|
"type": "string",
|
|
"description": "ID of the node to start execution from, from [List Datasource Plugins](/en/api-reference/knowledge-pipeline/list-datasource-plugins)."
|
|
},
|
|
"is_published": {
|
|
"type": "boolean",
|
|
"description": "Whether to run the published version of the pipeline instead of the current draft. Run the draft to test unpublished changes."
|
|
},
|
|
"response_mode": {
|
|
"type": "string",
|
|
"enum": [
|
|
"streaming",
|
|
"blocking"
|
|
],
|
|
"description": "Response mode for the pipeline execution. `streaming` returns a Server-Sent Events stream, `blocking` waits and returns the complete result."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"local_file": {
|
|
"summary": "Request Example - Local file",
|
|
"value": {
|
|
"inputs": {},
|
|
"datasource_type": "local_file",
|
|
"datasource_info_list": [
|
|
{
|
|
"reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"name": "quarterly-report.pdf"
|
|
}
|
|
],
|
|
"start_node_id": "1719288585006",
|
|
"is_published": true,
|
|
"response_mode": "blocking"
|
|
}
|
|
},
|
|
"online_document": {
|
|
"summary": "Request Example - Online document",
|
|
"value": {
|
|
"inputs": {},
|
|
"datasource_type": "online_document",
|
|
"datasource_info_list": [
|
|
{
|
|
"workspace_id": "ws-abc123",
|
|
"page": {
|
|
"page_id": "pg-def456",
|
|
"type": "page",
|
|
"page_name": "Product Roadmap"
|
|
},
|
|
"credential_id": "cred-789xyz"
|
|
}
|
|
],
|
|
"start_node_id": "1719288585006",
|
|
"is_published": true,
|
|
"response_mode": "streaming"
|
|
}
|
|
},
|
|
"website_crawl": {
|
|
"summary": "Request Example - Website crawl",
|
|
"value": {
|
|
"inputs": {},
|
|
"datasource_type": "website_crawl",
|
|
"datasource_info_list": [
|
|
{
|
|
"url": "https://example.com/docs/getting-started",
|
|
"title": "Getting Started Guide"
|
|
}
|
|
],
|
|
"start_node_id": "1719288585006",
|
|
"is_published": true,
|
|
"response_mode": "blocking"
|
|
}
|
|
},
|
|
"online_drive": {
|
|
"summary": "Request Example - Online drive",
|
|
"value": {
|
|
"inputs": {},
|
|
"datasource_type": "online_drive",
|
|
"datasource_info_list": [
|
|
{
|
|
"id": "file-abc123",
|
|
"type": "file",
|
|
"bucket": "my-bucket",
|
|
"name": "meeting-notes.docx"
|
|
}
|
|
],
|
|
"start_node_id": "1719288585006",
|
|
"is_published": true,
|
|
"response_mode": "blocking"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Pipeline execution result. Format depends on `response_mode`: streaming returns a `text/event-stream`, blocking returns a JSON object.",
|
|
"content": {
|
|
"text/event-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Server-Sent Events stream. Returned when `response_mode` is `streaming`; see [SSE Streaming](/en/api-reference/guides/streaming) for the wire format.\n\nKey events:\n\n- `workflow_started`: execution began\n- `node_started` / `node_finished`: per-node progress with `node_id`, `node_type`, `status`, `inputs`, `outputs`\n- `workflow_finished`: final result with `status`, `outputs`, `total_tokens`, `elapsed_time`\n- `ping`: keepalive"
|
|
}
|
|
},
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"description": "Complete pipeline execution result. Returned when `response_mode` is `blocking`.",
|
|
"additionalProperties": true
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Blocking Response Example",
|
|
"value": {
|
|
"task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
|
|
"data": {
|
|
"id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
|
|
"status": "succeeded",
|
|
"outputs": {},
|
|
"created_at": 1741267200,
|
|
"finished_at": 1741267210
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "`invalid_param` : The knowledge base has no processing pipeline configured, or the request body failed validation.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Pipeline not found"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "`forbidden` : API access is not enabled for this knowledge base.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"forbidden": {
|
|
"summary": "forbidden (api access)",
|
|
"value": {
|
|
"status": 403,
|
|
"code": "forbidden",
|
|
"message": "Dataset api access is not enabled."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "`not_found` : No knowledge base matches `dataset_id`.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"not_found": {
|
|
"summary": "not_found",
|
|
"value": {
|
|
"status": 404,
|
|
"code": "not_found",
|
|
"message": "Dataset not found."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`pipeline_run_error` : Pipeline execution failed.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"pipeline_run_error": {
|
|
"summary": "pipeline_run_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "pipeline_run_error",
|
|
"message": "Pipeline execution failed: connection timeout"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-mint": {
|
|
"href": "/en/api-reference/knowledge-pipeline/run-pipeline",
|
|
"metadata": {
|
|
"title": "Run Pipeline",
|
|
"sidebarTitle": "Run Pipeline"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"ApiKeyAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"bearerFormat": "API_KEY",
|
|
"description": "Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)).\n\nKeep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`)."
|
|
}
|
|
},
|
|
"responses": {
|
|
"SuccessResult": {
|
|
"description": "Operation successful.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"result": {
|
|
"type": "string",
|
|
"description": "Operation result. Always `success`."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"success": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"result": "success"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"schemas": {
|
|
"ChatRequest": {
|
|
"type": "object",
|
|
"required": [
|
|
"inputs",
|
|
"query",
|
|
"user"
|
|
],
|
|
"properties": {
|
|
"query": {
|
|
"type": "string",
|
|
"description": "The user's message."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"description": "Values for the app's input variables, keyed by variable name. The expected names and types come from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).",
|
|
"additionalProperties": true
|
|
},
|
|
"response_mode": {
|
|
"type": "string",
|
|
"enum": [
|
|
"streaming",
|
|
"blocking"
|
|
],
|
|
"description": "Mode of response return. Defaults to blocking when omitted.\n\n- `streaming` (recommended): the reply arrives as Server-Sent Events.\n- `blocking`: returns once generation completes. Long generations risk interruption: on Dify Cloud, the edge proxy may end the connection if the response doesn't arrive within its timeout.\n- Agent and New Agent apps support `streaming` only; a `blocking` request fails with 400."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. Conversations, messages, and files are visible only to requests carrying the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
},
|
|
"conversation_id": {
|
|
"type": "string",
|
|
"description": "ID of the conversation to continue. Omit it or pass an empty string to start a new conversation; the response returns a `conversation_id` to send with the next message. To resume an earlier conversation, get its ID from [List Conversations](/en/api-reference/conversations/list-conversations)."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"description": "Files to attach to the message. For a local file, first upload it via [Upload File](/en/api-reference/files/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`. New Agent apps accept file references but do not process their contents.",
|
|
"items": {
|
|
"type": "object",
|
|
"required": [
|
|
"type",
|
|
"transfer_method"
|
|
],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"image",
|
|
"document",
|
|
"audio",
|
|
"video",
|
|
"custom"
|
|
],
|
|
"description": "File type."
|
|
},
|
|
"transfer_method": {
|
|
"type": "string",
|
|
"enum": [
|
|
"remote_url",
|
|
"local_file"
|
|
],
|
|
"description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "url",
|
|
"description": "File URL (required when `transfer_method` is `remote_url`)."
|
|
},
|
|
"upload_file_id": {
|
|
"type": "string",
|
|
"description": "Uploaded file ID obtained from the [Upload File](/en/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`)."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"auto_generate_name": {
|
|
"type": "boolean",
|
|
"description": "Auto-generate conversation title. If `false`, use the [Rename Conversation](/en/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation.",
|
|
"default": true
|
|
},
|
|
"workflow_id": {
|
|
"type": "string",
|
|
"description": "Chatflow apps only. Specify a published workflow version ID to execute. If not provided, the latest published version is used. On Dify Cloud, pinning a version requires a paid plan."
|
|
}
|
|
}
|
|
},
|
|
"ChatCompletionResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"event": {
|
|
"type": "string",
|
|
"description": "Event type, fixed as `message`."
|
|
},
|
|
"task_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Task ID for request tracking and stop response API."
|
|
},
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique ID of this response event."
|
|
},
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints."
|
|
},
|
|
"conversation_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Conversation ID."
|
|
},
|
|
"mode": {
|
|
"type": "string",
|
|
"description": "App mode. `chat` for Chatbot apps, `agent-chat` for Agent apps, `advanced-chat` for Chatflow apps."
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Complete response content."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Metadata including usage and retriever resources.",
|
|
"properties": {
|
|
"usage": {
|
|
"$ref": "#/components/schemas/Usage"
|
|
},
|
|
"retriever_resources": {
|
|
"type": "array",
|
|
"description": "List of retriever resources used.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/RetrieverResource"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Message creation timestamp (Unix epoch seconds)."
|
|
}
|
|
}
|
|
},
|
|
"ChunkChatEvent": {
|
|
"type": "object",
|
|
"description": "Base schema for Server-Sent Event chunks in streaming mode.",
|
|
"properties": {
|
|
"event": {
|
|
"type": "string",
|
|
"description": "The type of event.",
|
|
"enum": [
|
|
"message",
|
|
"agent_message",
|
|
"agent_thought",
|
|
"tts_message",
|
|
"tts_message_end",
|
|
"message_file",
|
|
"message_end",
|
|
"message_replace",
|
|
"reasoning_chunk",
|
|
"workflow_started",
|
|
"workflow_finished",
|
|
"node_started",
|
|
"node_finished",
|
|
"node_retry",
|
|
"iteration_started",
|
|
"iteration_next",
|
|
"iteration_completed",
|
|
"loop_started",
|
|
"loop_next",
|
|
"loop_completed",
|
|
"workflow_paused",
|
|
"human_input_required",
|
|
"human_input_form_filled",
|
|
"human_input_form_timeout",
|
|
"agent_log",
|
|
"text_chunk",
|
|
"error",
|
|
"ping"
|
|
]
|
|
}
|
|
},
|
|
"discriminator": {
|
|
"propertyName": "event",
|
|
"mapping": {
|
|
"message": "#/components/schemas/StreamEventChatMessage",
|
|
"agent_message": "#/components/schemas/StreamEventChatAgentMessage",
|
|
"tts_message": "#/components/schemas/StreamEventChatTtsMessage",
|
|
"tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd",
|
|
"agent_thought": "#/components/schemas/StreamEventChatAgentThought",
|
|
"message_file": "#/components/schemas/StreamEventChatMessageFile",
|
|
"message_end": "#/components/schemas/StreamEventChatMessageEnd",
|
|
"message_replace": "#/components/schemas/StreamEventChatMessageReplace",
|
|
"error": "#/components/schemas/StreamEventChatError",
|
|
"ping": "#/components/schemas/StreamEventChatPing",
|
|
"reasoning_chunk": "#/components/schemas/StreamEventChatReasoningChunk",
|
|
"workflow_started": "#/components/schemas/StreamEventWorkflowStarted",
|
|
"workflow_finished": "#/components/schemas/StreamEventWorkflowFinished",
|
|
"node_started": "#/components/schemas/StreamEventNodeStarted",
|
|
"node_finished": "#/components/schemas/StreamEventNodeFinished",
|
|
"node_retry": "#/components/schemas/StreamEventNodeRetry",
|
|
"iteration_started": "#/components/schemas/StreamEventIterationStarted",
|
|
"iteration_next": "#/components/schemas/StreamEventIterationNext",
|
|
"iteration_completed": "#/components/schemas/StreamEventIterationCompleted",
|
|
"loop_started": "#/components/schemas/StreamEventLoopStarted",
|
|
"loop_next": "#/components/schemas/StreamEventLoopNext",
|
|
"loop_completed": "#/components/schemas/StreamEventLoopCompleted",
|
|
"workflow_paused": "#/components/schemas/StreamEventWorkflowPaused",
|
|
"human_input_required": "#/components/schemas/StreamEventHumanInputRequired",
|
|
"human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled",
|
|
"human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout",
|
|
"agent_log": "#/components/schemas/StreamEventAgentLog",
|
|
"text_chunk": "#/components/schemas/StreamEventChatTextChunk"
|
|
}
|
|
}
|
|
},
|
|
"StreamEventBase": {
|
|
"type": "object",
|
|
"description": "Base properties for stream events.",
|
|
"properties": {
|
|
"task_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Task ID."
|
|
},
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique message ID."
|
|
},
|
|
"conversation_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Conversation ID."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp."
|
|
}
|
|
}
|
|
},
|
|
"StreamEventChatMessage": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "LLM returned text chunk."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatAgentMessage": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "LLM returned text chunk (Agent mode)."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatTtsMessage": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "TTS audio stream event (base64 encoded Mp3). Available if auto-play enabled.",
|
|
"properties": {
|
|
"audio": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatTtsMessageEnd": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "TTS audio stream end event.",
|
|
"properties": {
|
|
"audio": {
|
|
"type": "string",
|
|
"description": "Empty string. Signals the end of the audio stream."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatAgentThought": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Agent thought, LLM thinking, tool call details (Agent mode).",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Agent thought ID."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Position of this thought in the sequence for the message."
|
|
},
|
|
"thought": {
|
|
"type": "string",
|
|
"description": "What LLM is thinking."
|
|
},
|
|
"observation": {
|
|
"type": "string",
|
|
"description": "Response from tool calls."
|
|
},
|
|
"tool": {
|
|
"type": "string",
|
|
"description": "List of tools called, split by `;`."
|
|
},
|
|
"tool_input": {
|
|
"type": "string",
|
|
"description": "Input of tools in JSON format."
|
|
},
|
|
"message_files": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"description": "File IDs of files related to this thought."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatMessageFile": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Message file event, a new file created by a tool.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "File unique ID."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "File type, e.g. `image`."
|
|
},
|
|
"belongs_to": {
|
|
"type": "string",
|
|
"description": "Who this file belongs to. Always `assistant` for tool-generated files."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "url",
|
|
"description": "Remote URL of the file."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatMessageEnd": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Message end event, streaming has ended.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique message ID."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Metadata including usage and retriever resources.",
|
|
"properties": {
|
|
"usage": {
|
|
"$ref": "#/components/schemas/Usage"
|
|
},
|
|
"retriever_resources": {
|
|
"type": "array",
|
|
"description": "List of retriever resources used.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/RetrieverResource"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatMessageReplace": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Message content replacement event (e.g., due to content moderation).",
|
|
"properties": {
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Replacement content."
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Reason for the content replacement."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatError": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Error event during streaming.",
|
|
"properties": {
|
|
"status": {
|
|
"type": "integer",
|
|
"description": "HTTP status code."
|
|
},
|
|
"code": {
|
|
"type": "string",
|
|
"description": "Error code."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Error message."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatPing": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Ping event to keep connection alive. Delivered as an `event: ping` line with no `data:` payload."
|
|
}
|
|
]
|
|
},
|
|
"Usage": {
|
|
"type": "object",
|
|
"description": "Model usage information.",
|
|
"properties": {
|
|
"prompt_tokens": {
|
|
"type": "integer",
|
|
"description": "Number of tokens in the prompt."
|
|
},
|
|
"prompt_unit_price": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "Unit price per prompt token."
|
|
},
|
|
"prompt_price_unit": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "Price unit for prompt tokens."
|
|
},
|
|
"prompt_price": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "Total price for prompt tokens."
|
|
},
|
|
"completion_tokens": {
|
|
"type": "integer",
|
|
"description": "Number of tokens in the completion."
|
|
},
|
|
"completion_unit_price": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "Unit price per completion token."
|
|
},
|
|
"completion_price_unit": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "Price unit for completion tokens."
|
|
},
|
|
"completion_price": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "Total price for completion tokens."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total number of tokens used."
|
|
},
|
|
"total_price": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "Total price for all tokens."
|
|
},
|
|
"currency": {
|
|
"type": "string",
|
|
"description": "Currency for pricing."
|
|
},
|
|
"latency": {
|
|
"type": "number",
|
|
"format": "double",
|
|
"description": "Latency in seconds."
|
|
}
|
|
}
|
|
},
|
|
"RetrieverResource": {
|
|
"type": "object",
|
|
"description": "Citation and attribution information for a retriever resource.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique ID of the retriever resource."
|
|
},
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "ID of the message this resource belongs to."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Position of the resource in the list."
|
|
},
|
|
"dataset_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "ID of the knowledge base."
|
|
},
|
|
"dataset_name": {
|
|
"type": "string",
|
|
"description": "Name of the knowledge base."
|
|
},
|
|
"document_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "ID of the document."
|
|
},
|
|
"document_name": {
|
|
"type": "string",
|
|
"description": "Name of the document."
|
|
},
|
|
"data_source_type": {
|
|
"type": "string",
|
|
"description": "Type of the data source."
|
|
},
|
|
"segment_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "ID of the specific chunk within the document."
|
|
},
|
|
"score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Similarity score of the resource."
|
|
},
|
|
"hit_count": {
|
|
"type": "integer",
|
|
"description": "Number of times this chunk was hit."
|
|
},
|
|
"word_count": {
|
|
"type": "integer",
|
|
"description": "Word count of the chunk."
|
|
},
|
|
"segment_position": {
|
|
"type": "integer",
|
|
"description": "Position of the chunk within the document."
|
|
},
|
|
"index_node_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the index node."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Content snippet from the resource."
|
|
},
|
|
"summary": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Summary of the chunk content."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp (Unix epoch seconds)."
|
|
}
|
|
}
|
|
},
|
|
"FileUploadResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique file ID."
|
|
},
|
|
"reference": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Opaque file reference used internally when attaching files in agent and tool contexts. Always `null` for files uploaded through this endpoint."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "File name."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "File size in bytes."
|
|
},
|
|
"extension": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "File extension."
|
|
},
|
|
"mime_type": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "MIME type of the file."
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "End-user ID of the uploader. Look up details with [Get End User Info](/en/api-reference/end-users/get-end-user-info)."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Upload timestamp (Unix epoch seconds)."
|
|
},
|
|
"preview_url": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Preview URL for the file."
|
|
},
|
|
"source_url": {
|
|
"type": "string",
|
|
"description": "Signed URL for downloading the file."
|
|
},
|
|
"original_url": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Original URL of the file."
|
|
},
|
|
"user_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "Unused; always `null`."
|
|
},
|
|
"tenant_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "ID of the associated tenant."
|
|
},
|
|
"conversation_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "ID of the associated conversation."
|
|
},
|
|
"file_key": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Unused; always `null`."
|
|
}
|
|
}
|
|
},
|
|
"EndUserDetail": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "End user ID."
|
|
},
|
|
"tenant_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Tenant ID."
|
|
},
|
|
"app_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "Application ID."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "End user type. Always `service-api` for Service API users."
|
|
},
|
|
"external_user_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/en/api-reference/chat-messages/send-chat-message))."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "End user name."
|
|
},
|
|
"is_anonymous": {
|
|
"type": "boolean",
|
|
"description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request."
|
|
},
|
|
"session_id": {
|
|
"type": "string",
|
|
"description": "Session identifier. Defaults to the `external_user_id` value."
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Creation timestamp."
|
|
},
|
|
"updated_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Last update timestamp."
|
|
}
|
|
}
|
|
},
|
|
"MessageFeedbackRequest": {
|
|
"type": "object",
|
|
"description": "Request body for submitting message feedback.",
|
|
"required": [
|
|
"user"
|
|
],
|
|
"properties": {
|
|
"rating": {
|
|
"type": "string",
|
|
"enum": [
|
|
"like",
|
|
"dislike",
|
|
null
|
|
],
|
|
"nullable": true,
|
|
"description": "Feedback rating. Set to `null` to revoke previously submitted feedback."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. Must match the `user` that received the message, since feedback is scoped to that end user. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Optional text feedback providing additional detail."
|
|
}
|
|
}
|
|
},
|
|
"AppFeedbacksResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of feedback items.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/FeedbackItem"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"FeedbackItem": {
|
|
"type": "object",
|
|
"description": "A single feedback item.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Feedback ID."
|
|
},
|
|
"app_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Application ID."
|
|
},
|
|
"conversation_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Conversation ID."
|
|
},
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Message ID."
|
|
},
|
|
"rating": {
|
|
"type": "string",
|
|
"description": "Feedback rating. `like` for positive, `dislike` for negative."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Optional text feedback."
|
|
},
|
|
"from_source": {
|
|
"type": "string",
|
|
"description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console."
|
|
},
|
|
"from_end_user_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "End user ID who submitted the feedback. Present when `from_source` is `user`."
|
|
},
|
|
"from_account_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "Account ID who submitted the feedback. Present when `from_source` is `admin`."
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Creation timestamp."
|
|
},
|
|
"updated_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Last update timestamp."
|
|
}
|
|
}
|
|
},
|
|
"SuggestedQuestionsResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"result": {
|
|
"type": "string",
|
|
"description": "Result status."
|
|
},
|
|
"data": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "List of suggested questions."
|
|
}
|
|
}
|
|
},
|
|
"ConversationHistoryResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Number of items per page."
|
|
},
|
|
"has_more": {
|
|
"type": "boolean",
|
|
"description": "Whether there are more messages."
|
|
},
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of messages.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ConversationMessageItem"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ConversationMessageItem": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Message ID."
|
|
},
|
|
"conversation_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Conversation ID."
|
|
},
|
|
"parent_message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "Parent message ID for threaded conversations."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Input variables for this message."
|
|
},
|
|
"query": {
|
|
"type": "string",
|
|
"description": "User query text."
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Assistant answer text."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Message status. `normal` for successful messages, `error` when generation failed."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if `status` is `error`."
|
|
},
|
|
"message_files": {
|
|
"type": "array",
|
|
"description": "Files attached to this message.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/MessageFileItem"
|
|
}
|
|
},
|
|
"feedback": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "User feedback for this message.",
|
|
"properties": {
|
|
"rating": {
|
|
"type": "string",
|
|
"description": "Feedback rating. `like` for positive, `dislike` for negative."
|
|
}
|
|
}
|
|
},
|
|
"retriever_resources": {
|
|
"type": "array",
|
|
"description": "Retriever resources used for this message.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/RetrieverResource"
|
|
}
|
|
},
|
|
"agent_thoughts": {
|
|
"type": "array",
|
|
"description": "Agent thoughts for this message.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/AgentThoughtItem"
|
|
}
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp (Unix epoch seconds)."
|
|
},
|
|
"extra_contents": {
|
|
"type": "array",
|
|
"description": "Additional execution content associated with this message, such as human input form data from Human Input nodes in Chatflow workflows.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/HumanInputContent"
|
|
}
|
|
},
|
|
"message_tokens": {
|
|
"type": "integer",
|
|
"description": "Number of tokens in the input message."
|
|
},
|
|
"answer_tokens": {
|
|
"type": "integer",
|
|
"description": "Number of tokens in the generated answer."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens used, the sum of `message_tokens` and `answer_tokens`."
|
|
},
|
|
"provider_response_latency": {
|
|
"type": "number",
|
|
"format": "double",
|
|
"description": "Model provider response latency in seconds."
|
|
},
|
|
"total_price": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"nullable": true,
|
|
"description": "Total price for the tokens used, or `null` when pricing is unavailable."
|
|
},
|
|
"currency": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Currency for `total_price` (for example, `USD`), or `null` when pricing is unavailable."
|
|
}
|
|
}
|
|
},
|
|
"MessageFileItem": {
|
|
"type": "object",
|
|
"description": "A file attached to a message.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "File ID."
|
|
},
|
|
"filename": {
|
|
"type": "string",
|
|
"description": "Original filename."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "File type, e.g., `image`."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "url",
|
|
"nullable": true,
|
|
"description": "Preview URL for the file."
|
|
},
|
|
"mime_type": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "MIME type of the file."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"nullable": true,
|
|
"description": "File size in bytes."
|
|
},
|
|
"transfer_method": {
|
|
"type": "string",
|
|
"description": "Transfer method used. `remote_url` for URL-based files, `local_file` for uploaded files, `tool_file` for tool-generated files."
|
|
},
|
|
"belongs_to": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Who this file belongs to. `user` for user-uploaded files, `assistant` for assistant-generated files."
|
|
},
|
|
"upload_file_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "Upload file ID if transferred via `local_file`."
|
|
}
|
|
}
|
|
},
|
|
"AgentThoughtItem": {
|
|
"type": "object",
|
|
"description": "An agent thought step in the message.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Agent thought ID."
|
|
},
|
|
"chain_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Chain ID for this thought."
|
|
},
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique message ID this thought belongs to."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Position of this thought."
|
|
},
|
|
"thought": {
|
|
"type": "string",
|
|
"description": "What LLM is thinking."
|
|
},
|
|
"tool": {
|
|
"type": "string",
|
|
"description": "Tools called, split by `;`."
|
|
},
|
|
"tool_labels": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Labels for tools used."
|
|
},
|
|
"tool_input": {
|
|
"type": "string",
|
|
"description": "Input of tools in JSON format."
|
|
},
|
|
"observation": {
|
|
"type": "string",
|
|
"description": "Response from tool calls."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "File IDs related to this thought."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp."
|
|
}
|
|
}
|
|
},
|
|
"ConversationsListResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Number of items per page."
|
|
},
|
|
"has_more": {
|
|
"type": "boolean",
|
|
"description": "Whether there are more conversations."
|
|
},
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of conversations.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ConversationListItem"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ConversationListItem": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Conversation ID."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Conversation name."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Input variables for the conversation."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Conversation status. `normal` for active conversations."
|
|
},
|
|
"introduction": {
|
|
"type": "string",
|
|
"description": "Conversation introduction."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp."
|
|
},
|
|
"updated_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Last update timestamp."
|
|
}
|
|
}
|
|
},
|
|
"ConversationRenameRequest": {
|
|
"type": "object",
|
|
"description": "Request body for renaming a conversation.",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "New conversation name. Required unless `auto_generate` is `true`."
|
|
},
|
|
"auto_generate": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Automatically generate the conversation name. When `true`, the `name` field is ignored."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
}
|
|
}
|
|
},
|
|
"ConversationVariablesResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Number of items per page."
|
|
},
|
|
"has_more": {
|
|
"type": "boolean",
|
|
"description": "Whether there is a next page."
|
|
},
|
|
"data": {
|
|
"type": "array",
|
|
"description": "List of conversation variables.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ConversationVariableItem"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ConversationVariableItem": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Variable ID."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Variable name."
|
|
},
|
|
"value_type": {
|
|
"type": "string",
|
|
"description": "Variable value type. Possible values: `string`, `number`, `object`, `secret`, `file`, `boolean`, `array[any]`, `array[string]`, `array[number]`, `array[object]`, `array[file]`, `array[boolean]`."
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"description": "Variable value (can be a JSON string for complex types)."
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "Variable description."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp."
|
|
},
|
|
"updated_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Last update timestamp."
|
|
}
|
|
}
|
|
},
|
|
"ConversationVariableUpdateRequest": {
|
|
"type": "object",
|
|
"description": "Request body for updating a conversation variable.",
|
|
"required": [
|
|
"value"
|
|
],
|
|
"properties": {
|
|
"value": {
|
|
"description": "The new value for the variable. Must match the variable's expected type."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
}
|
|
}
|
|
},
|
|
"AudioToTextRequest": {
|
|
"type": "object",
|
|
"description": "Request body for audio-to-text conversion.",
|
|
"required": [
|
|
"file"
|
|
],
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "Audio file to transcribe. Accepted MIME types: `audio/mp3`, `audio/m4a`, `audio/wav`, `audio/amr`, `audio/mpga`. Other types, including the common `audio/mpeg`, are rejected with `unsupported_audio_type`. Maximum size `30 MB`."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
}
|
|
}
|
|
},
|
|
"AudioToTextResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"text": {
|
|
"type": "string",
|
|
"description": "Output text from speech recognition."
|
|
}
|
|
}
|
|
},
|
|
"TextToAudioRequest": {
|
|
"type": "object",
|
|
"description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.",
|
|
"properties": {
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "ID of the message whose answer to voice. Takes priority over `text` when both are provided. Get message IDs from [List Conversation Messages](/en/api-reference/conversations/list-conversation-messages)."
|
|
},
|
|
"text": {
|
|
"type": "string",
|
|
"description": "Text to synthesize into speech."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
},
|
|
"voice": {
|
|
"type": "string",
|
|
"description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/en/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default."
|
|
},
|
|
"streaming": {
|
|
"type": "boolean",
|
|
"description": "Accepted for backward compatibility but has no effect. Whether the audio is streamed is determined by the configured TTS provider's output, not by this field."
|
|
}
|
|
}
|
|
},
|
|
"AppInfoResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Application name."
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "Application description."
|
|
},
|
|
"tags": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Application tags."
|
|
},
|
|
"mode": {
|
|
"type": "string",
|
|
"description": "Application mode. `completion` for text generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for Chatflow apps, `workflow` for Workflow apps, `agent` for New Agent apps."
|
|
},
|
|
"author_name": {
|
|
"type": "string",
|
|
"description": "Name of the application author."
|
|
}
|
|
}
|
|
},
|
|
"UserInputFormItem": {
|
|
"type": "object",
|
|
"oneOf": [
|
|
{
|
|
"$ref": "#/components/schemas/TextInputControlWrapper"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/ParagraphControlWrapper"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/SelectControlWrapper"
|
|
}
|
|
]
|
|
},
|
|
"TextInputControlWrapper": {
|
|
"title": "Text Input",
|
|
"type": "object",
|
|
"properties": {
|
|
"text-input": {
|
|
"$ref": "#/components/schemas/TextInputControl"
|
|
}
|
|
}
|
|
},
|
|
"ParagraphControlWrapper": {
|
|
"title": "Paragraph",
|
|
"type": "object",
|
|
"properties": {
|
|
"paragraph": {
|
|
"$ref": "#/components/schemas/ParagraphControl"
|
|
}
|
|
}
|
|
},
|
|
"SelectControlWrapper": {
|
|
"title": "Select",
|
|
"type": "object",
|
|
"properties": {
|
|
"select": {
|
|
"$ref": "#/components/schemas/SelectControl"
|
|
}
|
|
}
|
|
},
|
|
"TextInputControl": {
|
|
"type": "object",
|
|
"properties": {
|
|
"label": {
|
|
"type": "string",
|
|
"description": "Display label for the form field."
|
|
},
|
|
"variable": {
|
|
"type": "string",
|
|
"description": "Variable name used as the key in the `inputs` object."
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether this field must be filled before submission."
|
|
},
|
|
"default": {
|
|
"type": "string",
|
|
"description": "Default value pre-filled in the form field."
|
|
}
|
|
}
|
|
},
|
|
"ParagraphControl": {
|
|
"type": "object",
|
|
"properties": {
|
|
"label": {
|
|
"type": "string",
|
|
"description": "Display label for the form field."
|
|
},
|
|
"variable": {
|
|
"type": "string",
|
|
"description": "Variable name used as the key in the `inputs` object."
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether this field must be filled before submission."
|
|
},
|
|
"default": {
|
|
"type": "string",
|
|
"description": "Default value pre-filled in the form field."
|
|
}
|
|
}
|
|
},
|
|
"SelectControl": {
|
|
"type": "object",
|
|
"properties": {
|
|
"label": {
|
|
"type": "string",
|
|
"description": "Display label for the form field."
|
|
},
|
|
"variable": {
|
|
"type": "string",
|
|
"description": "Variable name used as the key in the `inputs` object."
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether a selection must be made before submission."
|
|
},
|
|
"default": {
|
|
"type": "string",
|
|
"description": "Default selected value."
|
|
},
|
|
"options": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "List of selectable values for this form control."
|
|
}
|
|
}
|
|
},
|
|
"AppMetaResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"tool_icons": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"oneOf": [
|
|
{
|
|
"title": "Icon URL",
|
|
"type": "string",
|
|
"format": "url",
|
|
"description": "URL of the icon."
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/ToolIconDetail"
|
|
}
|
|
]
|
|
},
|
|
"description": "Tool icons. Keys are tool names."
|
|
}
|
|
}
|
|
},
|
|
"ToolIconDetail": {
|
|
"title": "Emoji Icon",
|
|
"type": "object",
|
|
"description": "Detail of a tool icon using emoji.",
|
|
"properties": {
|
|
"background": {
|
|
"type": "string",
|
|
"description": "Background color in hex format."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Emoji content."
|
|
}
|
|
}
|
|
},
|
|
"WebAppSettingsResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"title": {
|
|
"type": "string",
|
|
"description": "WebApp title."
|
|
},
|
|
"chat_color_theme": {
|
|
"type": "string",
|
|
"description": "Chat color theme."
|
|
},
|
|
"chat_color_theme_inverted": {
|
|
"type": "boolean",
|
|
"description": "Whether the chat color theme is inverted."
|
|
},
|
|
"icon_type": {
|
|
"type": "string",
|
|
"description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons."
|
|
},
|
|
"icon": {
|
|
"type": "string",
|
|
"description": "Icon content (emoji or image ID)."
|
|
},
|
|
"icon_background": {
|
|
"type": "string",
|
|
"description": "Icon background color."
|
|
},
|
|
"icon_url": {
|
|
"type": "string",
|
|
"format": "url",
|
|
"nullable": true,
|
|
"description": "URL of the icon image."
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "WebApp description."
|
|
},
|
|
"copyright": {
|
|
"type": "string",
|
|
"description": "Copyright text."
|
|
},
|
|
"privacy_policy": {
|
|
"type": "string",
|
|
"description": "Privacy policy URL."
|
|
},
|
|
"input_placeholder": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Placeholder text shown in the WebApp message input box. `null` when not configured."
|
|
},
|
|
"custom_disclaimer": {
|
|
"type": "string",
|
|
"description": "Custom disclaimer text."
|
|
},
|
|
"default_language": {
|
|
"type": "string",
|
|
"description": "Default language code."
|
|
},
|
|
"show_workflow_steps": {
|
|
"type": "boolean",
|
|
"description": "Whether to show workflow steps."
|
|
},
|
|
"use_icon_as_answer_icon": {
|
|
"type": "boolean",
|
|
"description": "Whether to use the app icon as the answer icon."
|
|
}
|
|
}
|
|
},
|
|
"AnnotationListResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/AnnotationItem"
|
|
},
|
|
"description": "List of annotation items for the current page."
|
|
},
|
|
"has_more": {
|
|
"type": "boolean",
|
|
"description": "`true` if more pages are available beyond the current result set."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Number of items per page."
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total number of annotations matching the query."
|
|
},
|
|
"page": {
|
|
"type": "integer",
|
|
"description": "Current page number."
|
|
}
|
|
}
|
|
},
|
|
"AnnotationItem": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique annotation identifier."
|
|
},
|
|
"question": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Question text that triggers this annotation."
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Predefined answer returned when the annotation is matched."
|
|
},
|
|
"hit_count": {
|
|
"type": "integer",
|
|
"nullable": true,
|
|
"description": "Number of times this annotation has been matched and returned as a reply."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"nullable": true,
|
|
"description": "Creation timestamp (Unix epoch seconds)."
|
|
}
|
|
}
|
|
},
|
|
"CreateAnnotationRequest": {
|
|
"type": "object",
|
|
"description": "Request body for creating a new annotation.",
|
|
"required": [
|
|
"question",
|
|
"answer"
|
|
],
|
|
"properties": {
|
|
"question": {
|
|
"type": "string",
|
|
"description": "Question text the app matches incoming user input against."
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Answer returned when this annotation is matched."
|
|
}
|
|
}
|
|
},
|
|
"UpdateAnnotationRequest": {
|
|
"type": "object",
|
|
"description": "Request body for updating an annotation.",
|
|
"required": [
|
|
"question",
|
|
"answer"
|
|
],
|
|
"properties": {
|
|
"question": {
|
|
"type": "string",
|
|
"description": "New question text for the annotation."
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "New answer text for the annotation."
|
|
}
|
|
}
|
|
},
|
|
"InitialAnnotationReplySettingsRequest": {
|
|
"type": "object",
|
|
"description": "Request body for configuring annotation reply settings.",
|
|
"required": [
|
|
"score_threshold",
|
|
"embedding_provider_name",
|
|
"embedding_model_name"
|
|
],
|
|
"properties": {
|
|
"embedding_provider_name": {
|
|
"type": "string",
|
|
"description": "Embedding model provider (for example, `openai`). Get available providers from [Get Available Models](/en/api-reference/models/get-available-models)."
|
|
},
|
|
"embedding_model_name": {
|
|
"type": "string",
|
|
"description": "Embedding model used to vectorize annotations for matching (for example, `text-embedding-3-small`)."
|
|
},
|
|
"score_threshold": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Minimum similarity score for an annotation to be considered a match. Higher values require closer matches."
|
|
}
|
|
}
|
|
},
|
|
"InitialAnnotationReplySettingsResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"job_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Asynchronous job ID. Use with [Get Annotation Reply Job Status](/en/api-reference/annotations/get-annotation-reply-job-status) to track progress."
|
|
},
|
|
"job_status": {
|
|
"type": "string",
|
|
"description": "Current job status: `waiting` (queued) or `processing` (in progress). `completed` and `error` are returned only by [Get Annotation Reply Job Status](/en/api-reference/annotations/get-annotation-reply-job-status)."
|
|
}
|
|
}
|
|
},
|
|
"InitialAnnotationReplySettingsStatusResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"job_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Job ID from the [Configure Annotation Reply](/en/api-reference/annotations/configure-annotation-reply) call."
|
|
},
|
|
"job_status": {
|
|
"type": "string",
|
|
"description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed."
|
|
},
|
|
"error_msg": {
|
|
"type": "string",
|
|
"description": "Error message describing why the job failed. Empty string when `job_status` is not `error`."
|
|
}
|
|
}
|
|
},
|
|
"AppParametersResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"opening_statement": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Opening statement text."
|
|
},
|
|
"suggested_questions": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "List of suggested questions."
|
|
},
|
|
"suggested_questions_after_answer": {
|
|
"type": "object",
|
|
"description": "Configuration for suggested questions after an answer.",
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether this feature is enabled."
|
|
}
|
|
}
|
|
},
|
|
"speech_to_text": {
|
|
"type": "object",
|
|
"description": "Speech-to-text feature configuration.",
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether this feature is enabled."
|
|
}
|
|
}
|
|
},
|
|
"text_to_speech": {
|
|
"type": "object",
|
|
"description": "Text-to-speech feature configuration.",
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether this feature is enabled."
|
|
},
|
|
"voice": {
|
|
"type": "string",
|
|
"description": "Voice identifier for TTS."
|
|
},
|
|
"language": {
|
|
"type": "string",
|
|
"description": "Language for TTS."
|
|
},
|
|
"autoPlay": {
|
|
"type": "string",
|
|
"description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play."
|
|
}
|
|
}
|
|
},
|
|
"retriever_resource": {
|
|
"type": "object",
|
|
"description": "Knowledge retrieval citation resource configuration.",
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether this feature is enabled."
|
|
}
|
|
}
|
|
},
|
|
"annotation_reply": {
|
|
"type": "object",
|
|
"description": "Annotation reply feature configuration.",
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether this feature is enabled."
|
|
}
|
|
}
|
|
},
|
|
"more_like_this": {
|
|
"type": "object",
|
|
"description": "More-like-this feature configuration.",
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether this feature is enabled."
|
|
}
|
|
}
|
|
},
|
|
"sensitive_word_avoidance": {
|
|
"type": "object",
|
|
"description": "Content moderation feature configuration.",
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether this feature is enabled."
|
|
}
|
|
}
|
|
},
|
|
"user_input_form": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"oneOf": [
|
|
{
|
|
"title": "Text Input",
|
|
"type": "object",
|
|
"properties": {
|
|
"text-input": {
|
|
"type": "object",
|
|
"properties": {
|
|
"label": {
|
|
"type": "string",
|
|
"description": "Display label for the input field."
|
|
},
|
|
"variable": {
|
|
"type": "string",
|
|
"description": "Variable name used in the workflow."
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether this field is required."
|
|
},
|
|
"default": {
|
|
"type": "string",
|
|
"description": "Default value for the input field."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"title": "Paragraph",
|
|
"type": "object",
|
|
"properties": {
|
|
"paragraph": {
|
|
"type": "object",
|
|
"properties": {
|
|
"label": {
|
|
"type": "string",
|
|
"description": "Display label for the paragraph field."
|
|
},
|
|
"variable": {
|
|
"type": "string",
|
|
"description": "Variable name used in the workflow."
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether this field is required."
|
|
},
|
|
"default": {
|
|
"type": "string",
|
|
"description": "Default value for the paragraph field."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"title": "Select",
|
|
"type": "object",
|
|
"properties": {
|
|
"select": {
|
|
"type": "object",
|
|
"properties": {
|
|
"label": {
|
|
"type": "string",
|
|
"description": "Display label for the select field."
|
|
},
|
|
"variable": {
|
|
"type": "string",
|
|
"description": "Variable name used in the workflow."
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether this field is required."
|
|
},
|
|
"default": {
|
|
"type": "string",
|
|
"description": "Default selected value."
|
|
},
|
|
"options": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "List of selectable values for this form control."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"description": "User input form configuration."
|
|
},
|
|
"file_upload": {
|
|
"type": "object",
|
|
"description": "File upload configuration.",
|
|
"properties": {
|
|
"image": {
|
|
"type": "object",
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether image upload is enabled."
|
|
},
|
|
"number_limits": {
|
|
"type": "integer",
|
|
"description": "Maximum number of images that can be uploaded."
|
|
},
|
|
"detail": {
|
|
"type": "string",
|
|
"description": "Image detail level for vision models."
|
|
},
|
|
"transfer_methods": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Allowed transfer methods for image upload. `remote_url` for file URL, `local_file` for uploaded file."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"system_parameters": {
|
|
"type": "object",
|
|
"description": "System-level parameter limits.",
|
|
"properties": {
|
|
"file_size_limit": {
|
|
"type": "integer",
|
|
"description": "Maximum general file size in MB."
|
|
},
|
|
"image_file_size_limit": {
|
|
"type": "integer",
|
|
"description": "Maximum image file size in MB."
|
|
},
|
|
"audio_file_size_limit": {
|
|
"type": "integer",
|
|
"description": "Maximum audio file size in MB."
|
|
},
|
|
"video_file_size_limit": {
|
|
"type": "integer",
|
|
"description": "Maximum video file size in MB."
|
|
},
|
|
"workflow_file_upload_limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of files per workflow execution."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"StreamEventWorkflowStarted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Workflow execution started.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Workflow run ID."
|
|
},
|
|
"workflow_id": {
|
|
"type": "string",
|
|
"description": "Associated workflow ID."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Input variables for this workflow execution."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch seconds)."
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Reason for workflow start. `initial` for first start, `resumption` when resuming after a pause (e.g., after human input)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventWorkflowFinished": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Workflow execution finished.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Workflow run ID."
|
|
},
|
|
"workflow_id": {
|
|
"type": "string",
|
|
"description": "Associated workflow ID."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `stopped` if manually stopped, `partial-succeeded` if partially completed, `paused` when waiting for human input."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Workflow output data."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if execution failed."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"description": "Total execution time in seconds."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens consumed."
|
|
},
|
|
"total_steps": {
|
|
"type": "integer",
|
|
"description": "Total steps executed."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch seconds)."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"nullable": true,
|
|
"description": "Finish timestamp (Unix epoch seconds)."
|
|
},
|
|
"exceptions_count": {
|
|
"type": "integer",
|
|
"nullable": true,
|
|
"description": "Number of exceptions during execution."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"description": "Files generated during workflow execution."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventNodeStarted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Node execution started.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Node execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Node ID in the workflow graph."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type (e.g., `llm`, `knowledge-retrieval`, `code`)."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Node title."
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Execution index."
|
|
},
|
|
"predecessor_node_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the predecessor node."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Node input data. May be `null` in simplified API responses."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch seconds)."
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Additional metadata."
|
|
},
|
|
"iteration_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Iteration ID if this node runs inside an iteration."
|
|
},
|
|
"loop_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Loop ID if this node runs inside a loop."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventNodeFinished": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Node execution finished.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Node execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Node ID in the workflow graph."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Node title."
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Execution index."
|
|
},
|
|
"predecessor_node_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the predecessor node."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Node input data. May be `null` in simplified API responses."
|
|
},
|
|
"process_data": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Node processing data. May be `null` in simplified API responses."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Node output data. May be `null` in simplified API responses."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if node failed."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"description": "Node execution time in seconds."
|
|
},
|
|
"execution_metadata": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Execution metadata (e.g., token usage, model info). May be `null` in simplified API responses."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch seconds)."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Finish timestamp (Unix epoch seconds)."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"description": "Files generated by this node."
|
|
},
|
|
"iteration_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Iteration ID if this node runs inside an iteration."
|
|
},
|
|
"loop_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Loop ID if this node runs inside a loop."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventNodeRetry": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Node retry attempt.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Node execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Node ID in the workflow graph."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Node title."
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Execution index."
|
|
},
|
|
"predecessor_node_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the predecessor node."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Node input data."
|
|
},
|
|
"process_data": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Node processing data."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Node output data."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message for this retry attempt."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"description": "Execution time for this attempt in seconds."
|
|
},
|
|
"execution_metadata": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Execution metadata."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch seconds)."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Finish timestamp (Unix epoch seconds)."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"description": "Files generated during this retry."
|
|
},
|
|
"iteration_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Iteration ID if applicable."
|
|
},
|
|
"loop_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Loop ID if applicable."
|
|
},
|
|
"retry_index": {
|
|
"type": "integer",
|
|
"description": "Retry attempt index, starts at `0`."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventIterationStarted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Iteration loop started.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Iteration execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Iteration node ID."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Iteration node title."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch seconds)."
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Additional metadata."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Iteration metadata."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Iteration input data."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventIterationNext": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Iteration progressed to next item.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Iteration execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Iteration node ID."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Iteration node title."
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Current iteration index (0-based)."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Timestamp (Unix epoch seconds)."
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Additional metadata."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventIterationCompleted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Iteration loop completed.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Iteration execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Iteration node ID."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Iteration node title."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Iteration output data."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Iteration execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if iteration failed."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"description": "Total iteration time in seconds."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens consumed across all iterations."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch seconds)."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Finish timestamp (Unix epoch seconds)."
|
|
},
|
|
"steps": {
|
|
"type": "integer",
|
|
"description": "Total number of iteration steps executed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventLoopStarted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Loop started.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Loop execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Loop node ID."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Loop node title."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch seconds)."
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Additional metadata."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Loop metadata."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Loop input data."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventLoopNext": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Loop progressed to next iteration.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Loop execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Loop node ID."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Loop node title."
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Current loop index (0-based)."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Timestamp (Unix epoch seconds)."
|
|
},
|
|
"pre_loop_output": {
|
|
"description": "Output from the previous loop iteration."
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Additional metadata."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventLoopCompleted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Loop completed.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Loop execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Loop node ID."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Loop node title."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"additionalProperties": true,
|
|
"description": "Loop output data."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Loop execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if loop failed."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"description": "Total loop execution time in seconds."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens consumed across all loop iterations."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch seconds)."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Finish timestamp (Unix epoch seconds)."
|
|
},
|
|
"steps": {
|
|
"type": "integer",
|
|
"description": "Total number of loop steps executed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventHumanInputRequired": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"form_id": {
|
|
"type": "string",
|
|
"description": "Identifier for the form instance, surfaced in error messages and logs. Use `form_token` for Service API calls."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "ID of the Human Input node that produced this form."
|
|
},
|
|
"node_title": {
|
|
"type": "string",
|
|
"description": "Display title of the Human Input node."
|
|
},
|
|
"form_content": {
|
|
"type": "string",
|
|
"description": "Pre-rendered form body with workflow variables substituted."
|
|
},
|
|
"inputs": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Form input control type. Available values: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads)."
|
|
},
|
|
"output_variable_name": {
|
|
"type": "string",
|
|
"description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object."
|
|
},
|
|
"default": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Default value resolved from the workflow context. `null` when no default is configured.",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable."
|
|
},
|
|
"selector": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements."
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"description": "Literal default value when `type` is `constant`. Always a string."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"description": "Form input fields the recipient fills in."
|
|
},
|
|
"actions": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"maxLength": 20,
|
|
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
|
|
"description": "Identifier of the action button. Pass as `action` on [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form) when the recipient selects this button."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"maxLength": 100,
|
|
"description": "Button label shown to the recipient."
|
|
},
|
|
"button_style": {
|
|
"type": "string",
|
|
"description": "Visual style of the button. Available values: `primary`, `default`, `accent`, `ghost`."
|
|
}
|
|
}
|
|
},
|
|
"description": "Available user actions (buttons) the recipient can select when submitting."
|
|
},
|
|
"display_in_ui": {
|
|
"type": "boolean",
|
|
"description": "Whether the form is also shown in the Dify console UI."
|
|
},
|
|
"form_token": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Access token for [Get Human Input Form](/en/api-reference/human-input/get-human-input-form) and [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form). `null` when the Human Input node uses Email or Console delivery (the Service API can only operate on WebApp-delivered forms)."
|
|
},
|
|
"resolved_default_values": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
},
|
|
"description": "Pre-filled default values for the form inputs, keyed by input `output_variable_name`. All values are stringified."
|
|
},
|
|
"expiration_time": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp (seconds) after which the form can no longer be submitted."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventWorkflowPaused": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail) to retrieve results after execution."
|
|
},
|
|
"paused_nodes": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "List of paused node IDs."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Partial outputs at pause time."
|
|
},
|
|
"reasons": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"description": "Reasons for pausing."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Workflow execution status."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Total elapsed time in seconds."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens consumed."
|
|
},
|
|
"total_steps": {
|
|
"type": "integer",
|
|
"description": "Total steps executed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventHumanInputFormFilled": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "ID of the Human Input node whose form was filled."
|
|
},
|
|
"node_title": {
|
|
"type": "string",
|
|
"description": "Display title of the Human Input node."
|
|
},
|
|
"rendered_content": {
|
|
"type": "string",
|
|
"description": "Form body rendered with the recipient's submitted values (`form_content` on `human_input_required` is the unfilled template)."
|
|
},
|
|
"action_id": {
|
|
"type": "string",
|
|
"description": "Identifier of the action the recipient selected (matches the `action` value passed to [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form))."
|
|
},
|
|
"action_text": {
|
|
"type": "string",
|
|
"description": "Display text of the selected action."
|
|
},
|
|
"submitted_data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Values the recipient submitted, keyed by each form input's `output_variable_name`."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventHumanInputFormTimeout": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "Workflow execution run ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "ID of the Human Input node whose form expired."
|
|
},
|
|
"node_title": {
|
|
"type": "string",
|
|
"description": "Display title of the Human Input node."
|
|
},
|
|
"expiration_time": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp (seconds) when the form expired."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventAgentLog": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Agent log from an agent node within the workflow.",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"node_execution_id": {
|
|
"type": "string",
|
|
"description": "Node execution ID."
|
|
},
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Log entry ID."
|
|
},
|
|
"label": {
|
|
"type": "string",
|
|
"description": "Log entry label."
|
|
},
|
|
"parent_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Parent log entry ID for nested entries."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if applicable."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Log entry status."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Log entry data."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Additional metadata."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Node ID in the workflow graph."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatReasoningChunk": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "ID of the message this reasoning belongs to (mirrors the top-level `message_id`)."
|
|
},
|
|
"reasoning": {
|
|
"type": "string",
|
|
"description": "Chain-of-thought delta emitted by an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning. This stream is parallel to `message`; the `message` (answer) stream stays free of `<think>` tags."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the LLM node producing the reasoning. Lets you attribute reasoning when multiple LLM nodes run."
|
|
},
|
|
"is_final": {
|
|
"type": "boolean",
|
|
"description": "`true` marks the end of an LLM node's reasoning phase (the \"thinking finished\" signal); it may arrive with an empty `reasoning`."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventChatTextChunk": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkChatEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/StreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"text": {
|
|
"type": "string",
|
|
"description": "The text content chunk."
|
|
},
|
|
"from_variable_selector": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"nullable": true,
|
|
"description": "Source path of the text variable in the workflow."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowRunDetailResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Workflow run ID."
|
|
},
|
|
"workflow_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Workflow ID."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input."
|
|
},
|
|
"inputs": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Input variables of the workflow run, returned as a raw JSON string that clients must parse (e.g., `{\"query\": \"...\"}`). May be `null`."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Output data from the workflow. An empty object until outputs are available."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if the workflow failed."
|
|
},
|
|
"total_steps": {
|
|
"type": "integer",
|
|
"description": "Total number of workflow steps executed."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens consumed."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the workflow run was created."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"nullable": true,
|
|
"description": "Unix timestamp of when the workflow run finished."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"nullable": true,
|
|
"description": "Total time elapsed in seconds."
|
|
}
|
|
}
|
|
},
|
|
"WorkflowLogsResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"page": {
|
|
"type": "integer",
|
|
"description": "Current page number."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Number of items per page."
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total number of log entries."
|
|
},
|
|
"has_more": {
|
|
"type": "boolean",
|
|
"description": "Whether more pages are available."
|
|
},
|
|
"data": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/WorkflowLogItem"
|
|
},
|
|
"description": "List of workflow log entries."
|
|
}
|
|
}
|
|
},
|
|
"WorkflowLogItem": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Log entry ID."
|
|
},
|
|
"workflow_run": {
|
|
"$ref": "#/components/schemas/WorkflowRunSummary"
|
|
},
|
|
"created_from": {
|
|
"type": "string",
|
|
"description": "Source of the workflow run (e.g., `service-api`)."
|
|
},
|
|
"created_by_role": {
|
|
"type": "string",
|
|
"description": "Role of the creator (e.g., `end_user`, `account`)."
|
|
},
|
|
"created_by_account": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Account details if created by an admin user.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Account ID."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Account display name."
|
|
},
|
|
"email": {
|
|
"type": "string",
|
|
"description": "Account email address."
|
|
}
|
|
}
|
|
},
|
|
"created_by_end_user": {
|
|
"$ref": "#/components/schemas/EndUserSummary"
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the log entry was created."
|
|
},
|
|
"details": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Additional details for the log entry."
|
|
}
|
|
}
|
|
},
|
|
"WorkflowRunSummary": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Workflow run ID."
|
|
},
|
|
"version": {
|
|
"type": "string",
|
|
"description": "Workflow version identifier."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if the workflow failed."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Total time elapsed in seconds."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens consumed."
|
|
},
|
|
"total_steps": {
|
|
"type": "integer",
|
|
"description": "Total number of workflow steps executed."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the workflow run was created."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"nullable": true,
|
|
"description": "Unix timestamp of when the workflow run finished."
|
|
},
|
|
"exceptions_count": {
|
|
"type": "integer",
|
|
"description": "Number of exceptions that occurred during execution."
|
|
},
|
|
"triggered_from": {
|
|
"type": "string",
|
|
"description": "Source that triggered the workflow run. `app-run` for runs started from the app or API, `webhook` for runs started by a webhook trigger, `schedule` for runs started by a schedule trigger, `plugin` for runs started by a plugin trigger."
|
|
}
|
|
}
|
|
},
|
|
"EndUserSummary": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "End user ID."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "End user type."
|
|
},
|
|
"is_anonymous": {
|
|
"type": "boolean",
|
|
"description": "Whether the end user is anonymous."
|
|
},
|
|
"session_id": {
|
|
"type": "string",
|
|
"description": "Session identifier."
|
|
}
|
|
}
|
|
},
|
|
"HumanInputContent": {
|
|
"type": "object",
|
|
"description": "Execution content from a Human Input node, including form definition and submission data.",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"description": "ID of the workflow run this content belongs to."
|
|
},
|
|
"submitted": {
|
|
"type": "boolean",
|
|
"description": "Whether the human input form has been submitted."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "`human_input` for human input content."
|
|
},
|
|
"form_definition": {
|
|
"nullable": true,
|
|
"description": "Form definition from the Human Input node. `null` when the content represents a submission response.",
|
|
"$ref": "#/components/schemas/HumanInputFormDefinition"
|
|
},
|
|
"form_submission_data": {
|
|
"nullable": true,
|
|
"description": "Submitted form data. `null` when the form has not been submitted yet.",
|
|
"$ref": "#/components/schemas/HumanInputFormSubmissionData"
|
|
}
|
|
}
|
|
},
|
|
"HumanInputFormDefinition": {
|
|
"type": "object",
|
|
"description": "Definition of a human input form rendered by a Human Input node.",
|
|
"properties": {
|
|
"form_id": {
|
|
"type": "string",
|
|
"description": "Unique form identifier."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "ID of the Human Input node that generated this form."
|
|
},
|
|
"node_title": {
|
|
"type": "string",
|
|
"description": "Title of the Human Input node."
|
|
},
|
|
"form_content": {
|
|
"type": "string",
|
|
"description": "Markdown or text content displayed with the form."
|
|
},
|
|
"inputs": {
|
|
"type": "array",
|
|
"description": "Input fields in the form.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/FormInput"
|
|
}
|
|
},
|
|
"actions": {
|
|
"type": "array",
|
|
"description": "Action buttons available on the form.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/UserAction"
|
|
}
|
|
},
|
|
"display_in_ui": {
|
|
"type": "boolean",
|
|
"description": "Whether the form should be displayed in the UI."
|
|
},
|
|
"form_token": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Token for form submission authentication."
|
|
},
|
|
"resolved_default_values": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Resolved default values for form inputs, keyed by output variable name."
|
|
},
|
|
"expiration_time": {
|
|
"type": "integer",
|
|
"description": "Unix timestamp when the form expires."
|
|
}
|
|
}
|
|
},
|
|
"HumanInputFormSubmissionData": {
|
|
"type": "object",
|
|
"description": "Data from a submitted human input form.",
|
|
"properties": {
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "ID of the Human Input node."
|
|
},
|
|
"node_title": {
|
|
"type": "string",
|
|
"description": "Title of the Human Input node."
|
|
},
|
|
"rendered_content": {
|
|
"type": "string",
|
|
"description": "Rendered content of the form submission."
|
|
},
|
|
"action_id": {
|
|
"type": "string",
|
|
"description": "ID of the action button that was clicked."
|
|
},
|
|
"action_text": {
|
|
"type": "string",
|
|
"description": "Display text of the action button that was clicked."
|
|
}
|
|
}
|
|
},
|
|
"FormInput": {
|
|
"type": "object",
|
|
"description": "A form input field definition.",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Form input control type. Available values: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads)."
|
|
},
|
|
"output_variable_name": {
|
|
"type": "string",
|
|
"description": "Variable name where the input value is stored."
|
|
},
|
|
"default": {
|
|
"nullable": true,
|
|
"description": "Default value configuration for this input.",
|
|
"$ref": "#/components/schemas/FormInputDefault"
|
|
}
|
|
}
|
|
},
|
|
"FormInputDefault": {
|
|
"type": "object",
|
|
"description": "Default value configuration for a form input.",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"description": "`variable` for dynamic values from workflow variables, `constant` for static values."
|
|
},
|
|
"selector": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Variable selector path when `type` is `variable`."
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"description": "Static value when `type` is `constant`."
|
|
}
|
|
}
|
|
},
|
|
"UserAction": {
|
|
"type": "object",
|
|
"description": "An action button on a human input form.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique action identifier."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Button display text."
|
|
},
|
|
"button_style": {
|
|
"type": "string",
|
|
"description": "`primary`, `default`, `accent`, or `ghost`."
|
|
}
|
|
}
|
|
},
|
|
"WorkflowExecutionRequest": {
|
|
"type": "object",
|
|
"required": [
|
|
"inputs",
|
|
"user"
|
|
],
|
|
"properties": {
|
|
"inputs": {
|
|
"type": "object",
|
|
"description": "Key-value pairs for workflow input variables. Discover the variable names and types your app expects from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).\n\nFile-type variables take an array of file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`.",
|
|
"additionalProperties": {
|
|
"oneOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "number"
|
|
},
|
|
{
|
|
"type": "boolean"
|
|
},
|
|
{
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/InputFileObject"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"response_mode": {
|
|
"type": "string",
|
|
"enum": [
|
|
"streaming",
|
|
"blocking"
|
|
],
|
|
"description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events. When omitted, defaults to blocking behavior."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. Scopes data access: a workflow run and its files are only visible to later requests that carry the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/InputFileObject"
|
|
},
|
|
"nullable": true,
|
|
"description": "File list. Suitable when files need to be combined with text for input, available only when the model supports Vision capability. To attach a local file, first upload it via [Upload File](/en/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`."
|
|
}
|
|
}
|
|
},
|
|
"InputFileObject": {
|
|
"type": "object",
|
|
"required": [
|
|
"type",
|
|
"transfer_method"
|
|
],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"image",
|
|
"document",
|
|
"audio",
|
|
"video",
|
|
"custom"
|
|
],
|
|
"description": "File type."
|
|
},
|
|
"transfer_method": {
|
|
"type": "string",
|
|
"enum": [
|
|
"remote_url",
|
|
"local_file"
|
|
],
|
|
"description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "url",
|
|
"description": "File URL (when `transfer_method` is `remote_url`)."
|
|
},
|
|
"upload_file_id": {
|
|
"type": "string",
|
|
"description": "Uploaded file ID, obtained by uploading through the [Upload File](/en/api-reference/files/upload-file) API in advance (when `transfer_method` is `local_file`)."
|
|
}
|
|
},
|
|
"anyOf": [
|
|
{
|
|
"properties": {
|
|
"transfer_method": {
|
|
"enum": [
|
|
"remote_url"
|
|
]
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "url"
|
|
}
|
|
},
|
|
"required": [
|
|
"url"
|
|
],
|
|
"not": {
|
|
"required": [
|
|
"upload_file_id"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"transfer_method": {
|
|
"enum": [
|
|
"local_file"
|
|
]
|
|
},
|
|
"upload_file_id": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"upload_file_id"
|
|
],
|
|
"not": {
|
|
"required": [
|
|
"url"
|
|
]
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowBlockingResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"task_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/en/api-reference/workflow-runs/stop-workflow-task) to cancel a running workflow. Only valid during execution."
|
|
},
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail) to retrieve results after execution."
|
|
},
|
|
"data": {
|
|
"$ref": "#/components/schemas/WorkflowFinishedData"
|
|
}
|
|
}
|
|
},
|
|
"ChunkWorkflowEvent": {
|
|
"type": "object",
|
|
"required": [
|
|
"event"
|
|
],
|
|
"properties": {
|
|
"event": {
|
|
"type": "string",
|
|
"description": "The type of streaming event.",
|
|
"enum": [
|
|
"workflow_started",
|
|
"node_started",
|
|
"node_finished",
|
|
"node_retry",
|
|
"iteration_started",
|
|
"iteration_next",
|
|
"iteration_completed",
|
|
"loop_started",
|
|
"loop_next",
|
|
"loop_completed",
|
|
"reasoning_chunk",
|
|
"text_chunk",
|
|
"workflow_finished",
|
|
"tts_message",
|
|
"tts_message_end",
|
|
"workflow_paused",
|
|
"agent_log",
|
|
"human_input_required",
|
|
"human_input_form_filled",
|
|
"human_input_form_timeout",
|
|
"error",
|
|
"ping"
|
|
]
|
|
}
|
|
},
|
|
"discriminator": {
|
|
"propertyName": "event",
|
|
"mapping": {
|
|
"workflow_started": "#/components/schemas/WorkflowStreamEventWorkflowStarted",
|
|
"node_started": "#/components/schemas/WorkflowStreamEventNodeStarted",
|
|
"node_finished": "#/components/schemas/WorkflowStreamEventNodeFinished",
|
|
"node_retry": "#/components/schemas/WorkflowStreamEventNodeRetry",
|
|
"iteration_started": "#/components/schemas/WorkflowStreamEventIterationStarted",
|
|
"iteration_next": "#/components/schemas/WorkflowStreamEventIterationNext",
|
|
"iteration_completed": "#/components/schemas/WorkflowStreamEventIterationCompleted",
|
|
"loop_started": "#/components/schemas/WorkflowStreamEventLoopStarted",
|
|
"loop_next": "#/components/schemas/WorkflowStreamEventLoopNext",
|
|
"loop_completed": "#/components/schemas/WorkflowStreamEventLoopCompleted",
|
|
"reasoning_chunk": "#/components/schemas/StreamEventReasoningChunk",
|
|
"text_chunk": "#/components/schemas/StreamEventTextChunk",
|
|
"workflow_finished": "#/components/schemas/WorkflowStreamEventWorkflowFinished",
|
|
"tts_message": "#/components/schemas/StreamEventTtsMessage",
|
|
"tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd",
|
|
"error": "#/components/schemas/StreamEventError",
|
|
"ping": "#/components/schemas/StreamEventPing",
|
|
"workflow_paused": "#/components/schemas/WorkflowStreamEventWorkflowPaused",
|
|
"agent_log": "#/components/schemas/WorkflowStreamEventAgentLog",
|
|
"human_input_required": "#/components/schemas/WorkflowStreamEventHumanInputRequired",
|
|
"human_input_form_filled": "#/components/schemas/WorkflowStreamEventHumanInputFormFilled",
|
|
"human_input_form_timeout": "#/components/schemas/WorkflowStreamEventHumanInputFormTimeout"
|
|
}
|
|
}
|
|
},
|
|
"StreamEventReasoningChunk": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"reasoning": {
|
|
"type": "string",
|
|
"description": "Chain-of-thought delta emitted by an LLM node whose `reasoning_format` is `separated`. Concatenate consecutive `reasoning_chunk` events to rebuild the full reasoning. This stream is parallel to `text_chunk`; the `text` stream stays free of `<think>` tags."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the LLM node producing the reasoning. Lets you attribute reasoning when multiple LLM nodes run."
|
|
},
|
|
"is_final": {
|
|
"type": "boolean",
|
|
"description": "`true` marks the end of an LLM node's reasoning phase (the \"thinking finished\" signal); it may arrive with an empty `reasoning`."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventTextChunk": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"text": {
|
|
"type": "string",
|
|
"description": "The text content chunk."
|
|
},
|
|
"from_variable_selector": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"nullable": true,
|
|
"description": "Source path of the text variable in the workflow."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventTtsMessage": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"audio": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when this audio chunk was generated."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventTtsMessageEnd": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"audio": {
|
|
"type": "string",
|
|
"description": "Empty string. Signals the end of the audio stream."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the audio stream ended."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventError": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "integer",
|
|
"description": "HTTP status code of the error."
|
|
},
|
|
"code": {
|
|
"type": "string",
|
|
"description": "Error code."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Error message."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventPing": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Keep-alive ping event. No additional properties."
|
|
}
|
|
]
|
|
},
|
|
"WorkflowFinishedData": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Workflow run ID."
|
|
},
|
|
"workflow_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Workflow ID."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Output data from the workflow."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if the workflow failed."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Total time elapsed in seconds."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens consumed across all nodes."
|
|
},
|
|
"total_steps": {
|
|
"type": "integer",
|
|
"description": "Total number of workflow steps executed."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the workflow run was created."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"nullable": true,
|
|
"description": "Unix timestamp of when the workflow run finished."
|
|
},
|
|
"created_by": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Creator information. Only present in streaming `workflow_finished` events."
|
|
},
|
|
"exceptions_count": {
|
|
"type": "integer",
|
|
"nullable": true,
|
|
"description": "Number of exceptions encountered during execution. Only present in streaming `workflow_finished` events."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"nullable": true,
|
|
"description": "Files generated during workflow execution. Only present in streaming `workflow_finished` events."
|
|
}
|
|
}
|
|
},
|
|
"WorkflowStreamEventBase": {
|
|
"type": "object",
|
|
"properties": {
|
|
"task_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/en/api-reference/workflow-runs/stop-workflow-task) to cancel a running workflow. Only valid during execution."
|
|
},
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail) to retrieve results after execution."
|
|
}
|
|
}
|
|
},
|
|
"WorkflowStreamEventWorkflowStarted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Workflow run ID."
|
|
},
|
|
"workflow_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Workflow ID."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Input variables for this workflow run."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the workflow run started."
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Reason for the workflow start. `initial` for a new execution, `resumption` when resuming from a paused state."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventWorkflowFinished": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"$ref": "#/components/schemas/WorkflowFinishedData"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventNodeStarted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Node execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Node ID in the workflow graph."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type (e.g., `llm`, `code`, `template-transform`)."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Display name of the node."
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Execution sequence index."
|
|
},
|
|
"predecessor_node_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the predecessor node, if any."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Input variables for this node."
|
|
},
|
|
"inputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `inputs` data was truncated."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the node execution started."
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Additional metadata for the node execution."
|
|
},
|
|
"iteration_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Parent iteration ID if this node runs inside an iteration."
|
|
},
|
|
"loop_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Parent loop ID if this node runs inside a loop."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventNodeFinished": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Node execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Node ID in the workflow graph."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Display name of the node."
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Execution sequence index."
|
|
},
|
|
"predecessor_node_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the predecessor node, if any."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Input variables for this node."
|
|
},
|
|
"inputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `inputs` data was truncated."
|
|
},
|
|
"process_data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Processing data generated during node execution."
|
|
},
|
|
"process_data_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `process_data` was truncated."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Output data from the node."
|
|
},
|
|
"outputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `outputs` data was truncated."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Node execution status. `running` for in-progress, `succeeded` when completed, `failed` on error, `stopped` when manually halted, `exception` on unexpected failure."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if the node failed."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Time elapsed in seconds."
|
|
},
|
|
"execution_metadata": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Execution metadata including token usage.",
|
|
"properties": {
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"nullable": true,
|
|
"description": "Total tokens consumed by this node."
|
|
},
|
|
"total_price": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"nullable": true,
|
|
"description": "Total cost for this node execution."
|
|
},
|
|
"currency": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Currency of the cost (e.g., `USD`)."
|
|
}
|
|
}
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the node execution started."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the node execution finished."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"description": "Files generated by this node."
|
|
},
|
|
"iteration_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Parent iteration ID if this node runs inside an iteration."
|
|
},
|
|
"loop_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Parent loop ID if this node runs inside a loop."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventNodeRetry": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Node execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Node ID in the workflow graph."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Display name of the node."
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Execution sequence index."
|
|
},
|
|
"predecessor_node_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the predecessor node, if any."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true
|
|
},
|
|
"inputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `inputs` data was truncated."
|
|
},
|
|
"process_data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Processing data generated during node execution."
|
|
},
|
|
"process_data_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `process_data` was truncated."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true
|
|
},
|
|
"outputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `outputs` data was truncated."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Node execution status at the retry point."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message that triggered the retry."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Time elapsed in seconds."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64"
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64"
|
|
},
|
|
"retry_index": {
|
|
"type": "integer",
|
|
"description": "Zero-based retry attempt index."
|
|
},
|
|
"iteration_id": {
|
|
"type": "string",
|
|
"nullable": true
|
|
},
|
|
"loop_id": {
|
|
"type": "string",
|
|
"nullable": true
|
|
},
|
|
"execution_metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Metadata from the node execution."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"description": "Files produced by the node during execution."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventIterationStarted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Node execution ID."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Iteration node ID."
|
|
},
|
|
"node_type": {
|
|
"type": "string",
|
|
"description": "Node type (always `iteration`)."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Display name of the iteration node."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64"
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Input variables for the iteration."
|
|
},
|
|
"inputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `inputs` data was truncated."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Iteration metadata."
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventIterationNext": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"node_id": {
|
|
"type": "string"
|
|
},
|
|
"node_type": {
|
|
"type": "string"
|
|
},
|
|
"title": {
|
|
"type": "string"
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Current iteration index (zero-based)."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64"
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventIterationCompleted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"node_id": {
|
|
"type": "string"
|
|
},
|
|
"node_type": {
|
|
"type": "string"
|
|
},
|
|
"title": {
|
|
"type": "string"
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true
|
|
},
|
|
"outputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `outputs` data was truncated."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Input variables for the iteration."
|
|
},
|
|
"inputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `inputs` data was truncated."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp of when the iteration started."
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Additional metadata for the iteration."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Iteration completion status."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"format": "float"
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer"
|
|
},
|
|
"execution_metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Execution metadata including token usage."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64"
|
|
},
|
|
"steps": {
|
|
"type": "integer",
|
|
"description": "Number of iteration steps completed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventLoopStarted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"node_id": {
|
|
"type": "string"
|
|
},
|
|
"node_type": {
|
|
"type": "string"
|
|
},
|
|
"title": {
|
|
"type": "string"
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64"
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"inputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `inputs` data was truncated."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventLoopNext": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"node_id": {
|
|
"type": "string"
|
|
},
|
|
"node_type": {
|
|
"type": "string"
|
|
},
|
|
"title": {
|
|
"type": "string"
|
|
},
|
|
"index": {
|
|
"type": "integer",
|
|
"description": "Current loop iteration index (zero-based)."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64"
|
|
},
|
|
"pre_loop_output": {
|
|
"description": "Output from the previous loop iteration.",
|
|
"nullable": true
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventLoopCompleted": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid"
|
|
},
|
|
"node_id": {
|
|
"type": "string"
|
|
},
|
|
"node_type": {
|
|
"type": "string"
|
|
},
|
|
"title": {
|
|
"type": "string"
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true
|
|
},
|
|
"outputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `outputs` data was truncated."
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Input variables for the loop."
|
|
},
|
|
"inputs_truncated": {
|
|
"type": "boolean",
|
|
"description": "Whether the `inputs` data was truncated."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64"
|
|
},
|
|
"extras": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Additional metadata for the loop."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Loop completion status."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"format": "float"
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer"
|
|
},
|
|
"execution_metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Execution metadata including token usage."
|
|
},
|
|
"finished_at": {
|
|
"type": "integer",
|
|
"format": "int64"
|
|
},
|
|
"steps": {
|
|
"type": "integer",
|
|
"description": "Number of loop iterations completed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventHumanInputRequired": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"form_id": {
|
|
"type": "string",
|
|
"description": "Identifier for the form instance, surfaced in error messages and logs. Use `form_token` for Service API calls."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "ID of the Human Input node that produced this form."
|
|
},
|
|
"node_title": {
|
|
"type": "string",
|
|
"description": "Display title of the Human Input node."
|
|
},
|
|
"form_content": {
|
|
"type": "string",
|
|
"description": "Pre-rendered form body with workflow variables substituted."
|
|
},
|
|
"inputs": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Form input control type. Available values: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads)."
|
|
},
|
|
"output_variable_name": {
|
|
"type": "string",
|
|
"description": "Variable name used to reference this input's submitted value inside the workflow. Corresponds to the key in the submission `inputs` object."
|
|
},
|
|
"default": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Default value resolved from the workflow context. `null` when no default is configured.",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Source of the default. `constant` means `value` is used as a literal string; `variable` means `selector` points to a workflow variable."
|
|
},
|
|
"selector": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Variable reference path (for example, `[\"node_id\", \"var_name\"]`) when `type` is `variable`. Must contain at least two elements."
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"description": "Literal default value when `type` is `constant`. Always a string."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"description": "Form input fields the recipient fills in."
|
|
},
|
|
"actions": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"maxLength": 20,
|
|
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
|
|
"description": "Identifier of the action button. Pass as `action` on [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form) when the recipient selects this button."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"maxLength": 100,
|
|
"description": "Button label shown to the recipient."
|
|
},
|
|
"button_style": {
|
|
"type": "string",
|
|
"description": "Visual style of the button. Available values: `primary`, `default`, `accent`, `ghost`."
|
|
}
|
|
}
|
|
},
|
|
"description": "Available user actions (buttons) the recipient can select when submitting."
|
|
},
|
|
"display_in_ui": {
|
|
"type": "boolean",
|
|
"description": "Whether the form is also shown in the Dify console UI."
|
|
},
|
|
"form_token": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Access token for [Get Human Input Form](/en/api-reference/human-input/get-human-input-form) and [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form). `null` when the Human Input node uses Email or Console delivery (the Service API can only operate on WebApp-delivered forms)."
|
|
},
|
|
"resolved_default_values": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
},
|
|
"description": "Pre-filled default values for the form inputs, keyed by input `output_variable_name`. All values are stringified."
|
|
},
|
|
"expiration_time": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp (seconds) after which the form can no longer be submitted."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventWorkflowPaused": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"workflow_run_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail) to retrieve results after execution."
|
|
},
|
|
"paused_nodes": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "List of paused node IDs."
|
|
},
|
|
"outputs": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Partial outputs at pause time."
|
|
},
|
|
"reasons": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"description": "Reasons for pausing."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Workflow execution status."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp."
|
|
},
|
|
"elapsed_time": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Total elapsed time in seconds."
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"description": "Total tokens consumed."
|
|
},
|
|
"total_steps": {
|
|
"type": "integer",
|
|
"description": "Total steps executed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventHumanInputFormFilled": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "ID of the Human Input node whose form was filled."
|
|
},
|
|
"node_title": {
|
|
"type": "string",
|
|
"description": "Display title of the Human Input node."
|
|
},
|
|
"rendered_content": {
|
|
"type": "string",
|
|
"description": "Form body rendered with the recipient's submitted values (`form_content` on `human_input_required` is the unfilled template)."
|
|
},
|
|
"action_id": {
|
|
"type": "string",
|
|
"description": "Identifier of the action the recipient selected (matches the `action` value passed to [Submit Human Input Form](/en/api-reference/human-input/submit-human-input-form))."
|
|
},
|
|
"action_text": {
|
|
"type": "string",
|
|
"description": "Display text of the selected action."
|
|
},
|
|
"submitted_data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"nullable": true,
|
|
"description": "Values the recipient submitted, keyed by each form input's `output_variable_name`."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventHumanInputFormTimeout": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "ID of the Human Input node whose form expired."
|
|
},
|
|
"node_title": {
|
|
"type": "string",
|
|
"description": "Display title of the Human Input node."
|
|
},
|
|
"expiration_time": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp (seconds) when the form expired."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkflowStreamEventAgentLog": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkWorkflowEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/WorkflowStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"node_execution_id": {
|
|
"type": "string",
|
|
"description": "Node execution ID."
|
|
},
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Agent log entry ID."
|
|
},
|
|
"label": {
|
|
"type": "string",
|
|
"description": "Log label."
|
|
},
|
|
"parent_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Parent log entry ID."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if the agent step failed."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Agent step status."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Agent step data."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Agent step metadata."
|
|
},
|
|
"node_id": {
|
|
"type": "string",
|
|
"description": "Node ID."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"CompletionRequest": {
|
|
"type": "object",
|
|
"required": [
|
|
"inputs",
|
|
"user"
|
|
],
|
|
"properties": {
|
|
"inputs": {
|
|
"type": "object",
|
|
"description": "Values for the app's input variables, keyed by variable name. The expected names and types come from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).",
|
|
"additionalProperties": true
|
|
},
|
|
"query": {
|
|
"type": "string",
|
|
"default": "",
|
|
"description": "The text to process. Legacy field; newer apps pass this inside `inputs` instead."
|
|
},
|
|
"response_mode": {
|
|
"type": "string",
|
|
"enum": [
|
|
"streaming",
|
|
"blocking"
|
|
],
|
|
"description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "End-user identifier, defined by your app and unique within it. Messages and files are visible only to requests carrying the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity)."
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/InputFileObject"
|
|
},
|
|
"description": "Files to attach to the request. For a local file, first upload it via [Upload File](/en/api-reference/files/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`."
|
|
}
|
|
}
|
|
},
|
|
"CompletionResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"event": {
|
|
"type": "string",
|
|
"description": "Event type, fixed as `message`."
|
|
},
|
|
"task_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Task ID for request tracking and the [Stop Completion Message Generation](/en/api-reference/completion-messages/stop-completion-message-generation) API."
|
|
},
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique ID of this response event."
|
|
},
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints."
|
|
},
|
|
"mode": {
|
|
"type": "string",
|
|
"description": "App mode, fixed as `completion`."
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Complete response content."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Metadata including usage and retriever resources.",
|
|
"properties": {
|
|
"usage": {
|
|
"$ref": "#/components/schemas/Usage"
|
|
},
|
|
"retriever_resources": {
|
|
"type": "array",
|
|
"description": "List of retriever resources used.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/RetrieverResource"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Message creation timestamp (Unix epoch seconds)."
|
|
}
|
|
}
|
|
},
|
|
"ChunkCompletionEvent": {
|
|
"type": "object",
|
|
"properties": {
|
|
"event": {
|
|
"type": "string",
|
|
"enum": [
|
|
"message",
|
|
"message_end",
|
|
"message_file",
|
|
"tts_message",
|
|
"tts_message_end",
|
|
"message_replace",
|
|
"error",
|
|
"ping"
|
|
],
|
|
"description": "The type of streaming event."
|
|
}
|
|
},
|
|
"discriminator": {
|
|
"propertyName": "event",
|
|
"mapping": {
|
|
"message": "#/components/schemas/StreamEventMessage",
|
|
"message_end": "#/components/schemas/StreamEventMessageEnd",
|
|
"message_file": "#/components/schemas/StreamEventMessageFile",
|
|
"tts_message": "#/components/schemas/CompletionStreamEventTtsMessage",
|
|
"tts_message_end": "#/components/schemas/CompletionStreamEventTtsMessageEnd",
|
|
"message_replace": "#/components/schemas/StreamEventMessageReplace",
|
|
"error": "#/components/schemas/CompletionStreamEventError",
|
|
"ping": "#/components/schemas/CompletionStreamEventPing"
|
|
}
|
|
}
|
|
},
|
|
"StreamEventMessage": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkCompletionEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/CompletionStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "LLM returns text chunk event.",
|
|
"properties": {
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "LLM returned text chunk content."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventMessageEnd": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkCompletionEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/CompletionStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Message end event, receiving this event means streaming has ended.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique message ID."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Metadata including usage and retriever resources.",
|
|
"properties": {
|
|
"usage": {
|
|
"$ref": "#/components/schemas/Usage"
|
|
},
|
|
"retriever_resources": {
|
|
"type": "array",
|
|
"description": "List of retriever resources used.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/RetrieverResource"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"description": "Files generated during this message, such as model-generated images. `null` when no files were produced.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"related_id": {
|
|
"type": "string",
|
|
"description": "ID of the message file record."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "File type, e.g. `image`."
|
|
},
|
|
"filename": {
|
|
"type": "string",
|
|
"description": "File name."
|
|
},
|
|
"extension": {
|
|
"type": "string",
|
|
"description": "File extension, including the leading dot, e.g. `.png`."
|
|
},
|
|
"mime_type": {
|
|
"type": "string",
|
|
"description": "MIME type of the file."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "File size in bytes."
|
|
},
|
|
"transfer_method": {
|
|
"type": "string",
|
|
"description": "How the file is referenced: `remote_url`, `local_file`, or `tool_file`."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"description": "Accessible URL of the file."
|
|
},
|
|
"upload_file_id": {
|
|
"type": "string",
|
|
"description": "ID of the associated uploaded file."
|
|
},
|
|
"remote_url": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Original remote URL when the file was supplied as a remote URL; otherwise an empty string."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventMessageFile": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkCompletionEvent"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Message file event, a file (typically a model-generated image) produced during generation.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "File unique ID."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "File type, e.g. `image`."
|
|
},
|
|
"belongs_to": {
|
|
"type": "string",
|
|
"enum": [
|
|
"assistant"
|
|
],
|
|
"description": "Who this file belongs to, always `assistant` here."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "url",
|
|
"description": "Remote URL of the file."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventMessageReplace": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkCompletionEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/CompletionStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Message content replacement event (e.g., due to content moderation).",
|
|
"properties": {
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Replacement content."
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Reason for the content replacement."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"CompletionStreamEventBase": {
|
|
"type": "object",
|
|
"properties": {
|
|
"task_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Task ID."
|
|
},
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique message ID."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp."
|
|
}
|
|
}
|
|
},
|
|
"CompletionStreamEventTtsMessage": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkCompletionEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/CompletionStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "TTS audio stream event (base64 encoded MP3). Available if auto-play is enabled.",
|
|
"properties": {
|
|
"audio": {
|
|
"type": "string",
|
|
"format": "byte",
|
|
"description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"CompletionStreamEventTtsMessageEnd": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkCompletionEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/CompletionStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "TTS audio stream end event.",
|
|
"properties": {
|
|
"audio": {
|
|
"type": "string",
|
|
"description": "Empty string. Signals the end of the audio stream."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"CompletionStreamEventError": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkCompletionEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/CompletionStreamEventBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Error event during streaming.",
|
|
"properties": {
|
|
"status": {
|
|
"type": "integer",
|
|
"description": "HTTP status code."
|
|
},
|
|
"code": {
|
|
"type": "string",
|
|
"description": "Error code."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Error message."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"CompletionStreamEventPing": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkCompletionEvent"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Ping event to keep connection alive."
|
|
}
|
|
]
|
|
},
|
|
"Dataset": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier of the knowledge base."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Display name of the knowledge base. Unique within the workspace."
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "Optional text describing the purpose or contents of the knowledge base."
|
|
},
|
|
"provider": {
|
|
"type": "string",
|
|
"description": "Provider type. `vendor` for internally managed, `external` for external knowledge base connections."
|
|
},
|
|
"permission": {
|
|
"type": "string",
|
|
"description": "Controls who can access this knowledge base. Possible values: `only_me`, `all_team_members`, `partial_members`."
|
|
},
|
|
"data_source_type": {
|
|
"type": "string",
|
|
"description": "Data source type of the documents, `null` if not yet configured."
|
|
},
|
|
"indexing_technique": {
|
|
"type": "string",
|
|
"description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing."
|
|
},
|
|
"app_count": {
|
|
"type": "integer",
|
|
"description": "Number of applications currently using this knowledge base."
|
|
},
|
|
"document_count": {
|
|
"type": "integer",
|
|
"description": "Total number of documents in the knowledge base."
|
|
},
|
|
"word_count": {
|
|
"type": "integer",
|
|
"description": "Total word count across all documents."
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "ID of the user who created the knowledge base."
|
|
},
|
|
"author_name": {
|
|
"type": "string",
|
|
"description": "Display name of the creator."
|
|
},
|
|
"created_at": {
|
|
"type": "number",
|
|
"description": "Creation timestamp (Unix epoch in seconds)."
|
|
},
|
|
"updated_by": {
|
|
"type": "string",
|
|
"description": "ID of the user who last updated the knowledge base."
|
|
},
|
|
"updated_at": {
|
|
"type": "number",
|
|
"description": "Last update timestamp (Unix epoch in seconds)."
|
|
},
|
|
"embedding_model": {
|
|
"type": "string",
|
|
"description": "Name of the embedding model used for indexing."
|
|
},
|
|
"embedding_model_provider": {
|
|
"type": "string",
|
|
"description": "Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). Legacy knowledge bases may return the bare short form (e.g. `openai`)."
|
|
},
|
|
"embedding_available": {
|
|
"type": "boolean",
|
|
"description": "Whether the configured embedding model is currently available."
|
|
},
|
|
"retrieval_model_dict": {
|
|
"type": "object",
|
|
"description": "Retrieval configuration for the knowledge base.",
|
|
"properties": {
|
|
"search_method": {
|
|
"type": "string",
|
|
"description": "Search method used for retrieval. `keyword_search` for keyword matching, `semantic_search` for embedding-based similarity, `full_text_search` for full-text indexing, `hybrid_search` for a combination of semantic and keyword approaches."
|
|
},
|
|
"reranking_enable": {
|
|
"type": "boolean",
|
|
"description": "Whether reranking is enabled."
|
|
},
|
|
"reranking_mode": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Reranking mode. `reranking_model` for model-based reranking, `weighted_score` for score-based weighting. `null` if reranking is disabled."
|
|
},
|
|
"reranking_model": {
|
|
"type": "object",
|
|
"description": "Reranking model configuration.",
|
|
"properties": {
|
|
"reranking_provider_name": {
|
|
"type": "string",
|
|
"description": "Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). Legacy knowledge bases may return the bare short form (e.g. `cohere`)."
|
|
},
|
|
"reranking_model_name": {
|
|
"type": "string",
|
|
"description": "Name of the reranking model."
|
|
}
|
|
}
|
|
},
|
|
"weights": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Weight configuration for hybrid search.",
|
|
"properties": {
|
|
"weight_type": {
|
|
"type": "string",
|
|
"description": "Strategy for balancing semantic and keyword search weights."
|
|
},
|
|
"vector_setting": {
|
|
"type": "object",
|
|
"description": "Semantic search weight settings.",
|
|
"properties": {
|
|
"vector_weight": {
|
|
"type": "number",
|
|
"description": "Weight assigned to semantic (vector) search results."
|
|
},
|
|
"embedding_provider_name": {
|
|
"type": "string",
|
|
"description": "Provider of the embedding model used for vector search."
|
|
},
|
|
"embedding_model_name": {
|
|
"type": "string",
|
|
"description": "Name of the embedding model used for vector search."
|
|
}
|
|
}
|
|
},
|
|
"keyword_setting": {
|
|
"type": "object",
|
|
"description": "Keyword search weight settings.",
|
|
"properties": {
|
|
"keyword_weight": {
|
|
"type": "number",
|
|
"description": "Weight assigned to keyword search results."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"top_k": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results to return."
|
|
},
|
|
"score_threshold_enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether score threshold filtering is enabled."
|
|
},
|
|
"score_threshold": {
|
|
"type": "number",
|
|
"description": "Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`."
|
|
}
|
|
}
|
|
},
|
|
"summary_index_setting": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Summary index configuration.",
|
|
"properties": {
|
|
"enable": {
|
|
"type": "boolean",
|
|
"description": "Whether summary indexing is enabled."
|
|
},
|
|
"model_name": {
|
|
"type": "string",
|
|
"description": "Name of the model used for generating summaries."
|
|
},
|
|
"model_provider_name": {
|
|
"type": "string",
|
|
"description": "Provider of the summary generation model."
|
|
},
|
|
"summary_prompt": {
|
|
"type": "string",
|
|
"description": "Prompt template used for summary generation."
|
|
}
|
|
}
|
|
},
|
|
"tags": {
|
|
"type": "array",
|
|
"description": "Tags associated with this knowledge base.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Tag identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Tag name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Tag type. Always `knowledge` for knowledge base tags."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"doc_form": {
|
|
"type": "string",
|
|
"description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction."
|
|
},
|
|
"external_knowledge_info": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Connection details for external knowledge bases. Present when `provider` is `external`.",
|
|
"properties": {
|
|
"external_knowledge_id": {
|
|
"type": "string",
|
|
"description": "ID of the external knowledge base."
|
|
},
|
|
"external_knowledge_api_id": {
|
|
"type": "string",
|
|
"description": "ID of the external knowledge API connection."
|
|
},
|
|
"external_knowledge_api_name": {
|
|
"type": "string",
|
|
"description": "Display name of the external knowledge API."
|
|
},
|
|
"external_knowledge_api_endpoint": {
|
|
"type": "string",
|
|
"description": "Endpoint URL of the external knowledge API."
|
|
}
|
|
}
|
|
},
|
|
"external_retrieval_model": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Retrieval settings for external knowledge bases. `null` for internal knowledge bases.",
|
|
"properties": {
|
|
"top_k": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results to return from the external knowledge base."
|
|
},
|
|
"score_threshold": {
|
|
"type": "number",
|
|
"description": "Minimum similarity score threshold."
|
|
},
|
|
"score_threshold_enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether score threshold filtering is enabled."
|
|
}
|
|
}
|
|
},
|
|
"doc_metadata": {
|
|
"type": "array",
|
|
"description": "Metadata field definitions for the knowledge base.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Metadata field identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Metadata field name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Metadata field value type."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"built_in_field_enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether built-in metadata fields (e.g., `document_name`, `uploader`) are enabled."
|
|
},
|
|
"pipeline_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Pipeline ID, if a custom processing pipeline is configured."
|
|
},
|
|
"runtime_mode": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Runtime processing mode."
|
|
},
|
|
"chunk_structure": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Chunk structure configuration."
|
|
},
|
|
"icon_info": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Icon display configuration for the knowledge base.",
|
|
"properties": {
|
|
"icon_type": {
|
|
"type": "string",
|
|
"description": "Type of icon."
|
|
},
|
|
"icon": {
|
|
"type": "string",
|
|
"description": "Icon identifier or emoji."
|
|
},
|
|
"icon_background": {
|
|
"type": "string",
|
|
"description": "Background color for the icon."
|
|
},
|
|
"icon_url": {
|
|
"type": "string",
|
|
"description": "URL of a custom icon image."
|
|
}
|
|
}
|
|
},
|
|
"is_published": {
|
|
"type": "boolean",
|
|
"description": "Whether the knowledge base is published."
|
|
},
|
|
"total_documents": {
|
|
"type": "integer",
|
|
"description": "Total number of documents."
|
|
},
|
|
"total_available_documents": {
|
|
"type": "integer",
|
|
"description": "Number of documents that are enabled and available."
|
|
},
|
|
"enable_api": {
|
|
"type": "boolean",
|
|
"description": "Whether API access is enabled for this knowledge base."
|
|
},
|
|
"is_multimodal": {
|
|
"type": "boolean",
|
|
"description": "Whether multimodal content processing is enabled."
|
|
},
|
|
"maintainer": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Display name of the knowledge base maintainer. `null` if not set."
|
|
},
|
|
"partial_member_list": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Account IDs of members granted access when `permission` is `partial_members`. Always present on the update response; on the detail response, present only when `permission` is `partial_members`."
|
|
}
|
|
}
|
|
},
|
|
"Document": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier of the document."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Display position of the document in the list."
|
|
},
|
|
"data_source_type": {
|
|
"type": "string",
|
|
"description": "How the document was created. `upload_file` for file uploads, `notion_import` for Notion imports."
|
|
},
|
|
"data_source_info": {
|
|
"type": "object",
|
|
"description": "Raw data source information, varies by `data_source_type`."
|
|
},
|
|
"data_source_detail_dict": {
|
|
"type": "object",
|
|
"description": "Detailed data source information including file details."
|
|
},
|
|
"dataset_process_rule_id": {
|
|
"type": "string",
|
|
"description": "ID of the processing rule applied to this document."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Document name."
|
|
},
|
|
"created_from": {
|
|
"type": "string",
|
|
"description": "Origin of the document. `api` for API creation, `web` for UI creation."
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "ID of the user who created the document."
|
|
},
|
|
"created_at": {
|
|
"type": "number",
|
|
"description": "Creation timestamp (Unix epoch in seconds)."
|
|
},
|
|
"tokens": {
|
|
"type": "integer",
|
|
"description": "Total number of tokens in the document."
|
|
},
|
|
"indexing_status": {
|
|
"type": "string",
|
|
"description": "Current indexing status. `waiting` for queued, `parsing` while extracting content, `cleaning` while removing noise, `splitting` while chunking, `indexing` while building vectors, `completed` when ready, `error` if failed, `paused` if manually paused."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if indexing failed. `null` when no error."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether the document is enabled for retrieval."
|
|
},
|
|
"disabled_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when the document was disabled. `null` if enabled."
|
|
},
|
|
"disabled_by": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the user who disabled the document. `null` if enabled."
|
|
},
|
|
"archived": {
|
|
"type": "boolean",
|
|
"description": "Whether the document is archived."
|
|
},
|
|
"display_status": {
|
|
"type": "string",
|
|
"description": "User-facing display status derived from `indexing_status` and `enabled` state."
|
|
},
|
|
"word_count": {
|
|
"type": "integer",
|
|
"description": "Total word count of the document."
|
|
},
|
|
"hit_count": {
|
|
"type": "integer",
|
|
"description": "Number of times the document has been matched in retrieval queries."
|
|
},
|
|
"doc_form": {
|
|
"type": "string",
|
|
"description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction."
|
|
},
|
|
"doc_metadata": {
|
|
"type": "array",
|
|
"description": "Metadata values assigned to this document.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Metadata field identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Metadata field name."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "Metadata field value type."
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"description": "Metadata value for this document."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"summary_index_status": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Status of the summary index for this document. `null` if summary indexing is not configured."
|
|
},
|
|
"need_summary": {
|
|
"type": "boolean",
|
|
"description": "Whether a summary needs to be generated for this document."
|
|
}
|
|
}
|
|
},
|
|
"Segment": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier of the chunk."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Position of the chunk within the document."
|
|
},
|
|
"document_id": {
|
|
"type": "string",
|
|
"description": "ID of the document this chunk belongs to."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Text content of the chunk."
|
|
},
|
|
"sign_content": {
|
|
"type": "string",
|
|
"description": "Signed content hash for integrity verification."
|
|
},
|
|
"answer": {
|
|
"type": "string",
|
|
"description": "Answer content, used in Q&A mode documents."
|
|
},
|
|
"word_count": {
|
|
"type": "integer",
|
|
"description": "Word count of the chunk content."
|
|
},
|
|
"tokens": {
|
|
"type": "integer",
|
|
"description": "Token count of the chunk content."
|
|
},
|
|
"keywords": {
|
|
"type": "array",
|
|
"description": "Keywords associated with this chunk for keyword-based retrieval.",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"index_node_id": {
|
|
"type": "string",
|
|
"description": "ID of the index node in the vector store."
|
|
},
|
|
"index_node_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the indexed content, used to detect changes."
|
|
},
|
|
"hit_count": {
|
|
"type": "integer",
|
|
"description": "Number of times this chunk has been matched in retrieval queries."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether the chunk is enabled for retrieval."
|
|
},
|
|
"disabled_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when the chunk was disabled. `null` if enabled."
|
|
},
|
|
"disabled_by": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "ID of the user who disabled the chunk. `null` if enabled."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Current indexing status of the chunk, e.g. `completed`, `indexing`, `error`."
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "ID of the user who created the chunk."
|
|
},
|
|
"created_at": {
|
|
"type": "number",
|
|
"description": "Creation timestamp (Unix epoch in seconds)."
|
|
},
|
|
"updated_at": {
|
|
"type": "number",
|
|
"description": "Last update timestamp (Unix epoch in seconds)."
|
|
},
|
|
"updated_by": {
|
|
"type": "string",
|
|
"description": "ID of the user who last updated the chunk."
|
|
},
|
|
"indexing_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when indexing started. `null` if not yet started."
|
|
},
|
|
"completed_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when indexing completed. `null` if not yet completed."
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if indexing failed. `null` when no error."
|
|
},
|
|
"stopped_at": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Timestamp when indexing was stopped. `null` if not stopped."
|
|
},
|
|
"child_chunks": {
|
|
"type": "array",
|
|
"description": "Child chunks belonging to this chunk. Only present for hierarchical mode documents.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ChildChunk"
|
|
}
|
|
},
|
|
"attachments": {
|
|
"type": "array",
|
|
"description": "Files attached to this chunk.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Attachment file identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Original file name."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "File size in bytes."
|
|
},
|
|
"extension": {
|
|
"type": "string",
|
|
"description": "File extension."
|
|
},
|
|
"mime_type": {
|
|
"type": "string",
|
|
"description": "MIME type of the file."
|
|
},
|
|
"source_url": {
|
|
"type": "string",
|
|
"description": "URL to access the attachment."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"summary": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "AI-generated summary of the chunk content. `null` if summary indexing is not enabled."
|
|
}
|
|
}
|
|
},
|
|
"ChildChunk": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier of the child chunk."
|
|
},
|
|
"segment_id": {
|
|
"type": "string",
|
|
"description": "ID of the parent chunk this child chunk belongs to."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Text content of the child chunk."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Position of the child chunk within the parent chunk."
|
|
},
|
|
"word_count": {
|
|
"type": "integer",
|
|
"description": "Word count of the child chunk content."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "How the child chunk was created. Child chunks created or updated through the API are always `customized`. System-generated child chunks are `automatic`."
|
|
},
|
|
"created_at": {
|
|
"type": "number",
|
|
"description": "Creation timestamp (Unix epoch in seconds)."
|
|
},
|
|
"updated_at": {
|
|
"type": "number",
|
|
"description": "Last update timestamp (Unix epoch in seconds)."
|
|
}
|
|
}
|
|
},
|
|
"RetrievalModel": {
|
|
"type": "object",
|
|
"required": [
|
|
"search_method",
|
|
"reranking_enable",
|
|
"top_k",
|
|
"score_threshold_enabled"
|
|
],
|
|
"properties": {
|
|
"search_method": {
|
|
"type": "string",
|
|
"description": "Search method used for retrieval.",
|
|
"enum": [
|
|
"keyword_search",
|
|
"semantic_search",
|
|
"full_text_search",
|
|
"hybrid_search"
|
|
]
|
|
},
|
|
"reranking_enable": {
|
|
"type": "boolean",
|
|
"description": "Whether reranking is enabled."
|
|
},
|
|
"reranking_model": {
|
|
"type": "object",
|
|
"description": "Reranking model configuration.",
|
|
"properties": {
|
|
"reranking_provider_name": {
|
|
"type": "string",
|
|
"description": "Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). A bare name like `cohere` expands to `langgenius/<name>/<name>` and works only for langgenius-published plugins.\n\nGet valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=rerank`."
|
|
},
|
|
"reranking_model_name": {
|
|
"type": "string",
|
|
"description": "Name of the reranking model."
|
|
}
|
|
}
|
|
},
|
|
"reranking_mode": {
|
|
"type": "string",
|
|
"enum": [
|
|
"reranking_model",
|
|
"weighted_score"
|
|
],
|
|
"nullable": true,
|
|
"description": "Reranking mode. Required when `reranking_enable` is `true`."
|
|
},
|
|
"top_k": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results to return."
|
|
},
|
|
"score_threshold_enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether score threshold filtering is enabled."
|
|
},
|
|
"score_threshold": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`."
|
|
},
|
|
"weights": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Weight configuration for hybrid search.",
|
|
"properties": {
|
|
"weight_type": {
|
|
"type": "string",
|
|
"description": "Strategy for balancing semantic and keyword search weights.",
|
|
"enum": [
|
|
"semantic_first",
|
|
"keyword_first",
|
|
"customized"
|
|
]
|
|
},
|
|
"vector_setting": {
|
|
"type": "object",
|
|
"description": "Semantic search weight settings.",
|
|
"properties": {
|
|
"vector_weight": {
|
|
"type": "number",
|
|
"description": "Weight assigned to semantic (vector) search results."
|
|
},
|
|
"embedding_provider_name": {
|
|
"type": "string",
|
|
"description": "Provider of the embedding model used for vector search."
|
|
},
|
|
"embedding_model_name": {
|
|
"type": "string",
|
|
"description": "Name of the embedding model used for vector search."
|
|
}
|
|
}
|
|
},
|
|
"keyword_setting": {
|
|
"type": "object",
|
|
"description": "Keyword search weight settings.",
|
|
"properties": {
|
|
"keyword_weight": {
|
|
"type": "number",
|
|
"description": "Weight assigned to keyword search results."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"metadata_filtering_conditions": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Restrict retrieval to chunks whose document metadata matches the given conditions. Conditions are evaluated server-side against document metadata fields.",
|
|
"properties": {
|
|
"logical_operator": {
|
|
"type": "string",
|
|
"enum": [
|
|
"and",
|
|
"or"
|
|
],
|
|
"default": "and",
|
|
"nullable": true,
|
|
"description": "How to combine multiple conditions."
|
|
},
|
|
"conditions": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"description": "List of metadata conditions to evaluate.",
|
|
"items": {
|
|
"type": "object",
|
|
"required": [
|
|
"name",
|
|
"comparison_operator"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Metadata field name to compare against."
|
|
},
|
|
"comparison_operator": {
|
|
"type": "string",
|
|
"description": "Comparison to apply, by metadata type:\n\n- String or array metadata: `contains`, `not contains`, `start with`, `end with`, `is`, `is not`, `empty`, `not empty`, `in`, `not in`\n- Numeric metadata: `=`, `≠`, `>`, `<`, `≥`, `≤`\n- Time metadata: `before`, `after`",
|
|
"enum": [
|
|
"contains",
|
|
"not contains",
|
|
"start with",
|
|
"end with",
|
|
"is",
|
|
"is not",
|
|
"empty",
|
|
"not empty",
|
|
"in",
|
|
"not in",
|
|
"=",
|
|
"≠",
|
|
">",
|
|
"<",
|
|
"≥",
|
|
"≤",
|
|
"before",
|
|
"after"
|
|
]
|
|
},
|
|
"value": {
|
|
"nullable": true,
|
|
"description": "Value to compare against. Type depends on `comparison_operator`: string for most string operators, array of strings for `in` and `not in`, number for numeric operators, and omitted for `empty` and `not empty`.",
|
|
"oneOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"type": "number"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|