diff --git a/api/controllers/common/controller_schemas.py b/api/controllers/common/controller_schemas.py index ec0b4241363..b47a1a013a0 100644 --- a/api/controllers/common/controller_schemas.py +++ b/api/controllers/common/controller_schemas.py @@ -141,4 +141,7 @@ class TextToAudioPayload(BaseModel): message_id: str | None = Field(default=None, description="Message ID") voice: str | None = Field(default=None, description="Voice to use for TTS") text: str | None = Field(default=None, description="Text to convert to audio") - streaming: bool | None = Field(default=None, description="Enable streaming response") + streaming: bool | None = Field( + default=None, + description="Reserved for compatibility; TTS response streaming is determined by the provider output.", + ) diff --git a/api/controllers/service_api/app/annotation.py b/api/controllers/service_api/app/annotation.py index f1b345759a7..d2522c4a41b 100644 --- a/api/controllers/service_api/app/annotation.py +++ b/api/controllers/service_api/app/annotation.py @@ -65,6 +65,18 @@ register_response_schema_models(service_api_ns, AnnotationJobStatusResponse) @service_api_ns.route("/apps/annotation-reply/") class AnnotationReplyActionApi(Resource): + @service_api_ns.doc( + summary="Configure Annotation Reply", + description=( + "Enables or disables the annotation reply feature. Requires embedding model configuration " + "when enabling. Executes asynchronously — use [Get Annotation Reply Job " + "Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress." + ), + tags=["Annotations"], + responses={ + 200: "Annotation reply settings task initiated.", + }, + ) @service_api_ns.expect(service_api_ns.models[AnnotationReplyActionPayload.__name__]) @service_api_ns.doc("annotation_reply_action") @service_api_ns.doc(description="Enable or disable annotation reply feature") @@ -99,6 +111,18 @@ class AnnotationReplyActionApi(Resource): @service_api_ns.route("/apps/annotation-reply//status/") class AnnotationReplyActionStatusApi(Resource): + @service_api_ns.doc( + summary="Get Annotation Reply Job Status", + description=( + "Retrieves the status of an asynchronous annotation reply configuration job started by " + "[Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply)." + ), + tags=["Annotations"], + responses={ + 200: "Successfully retrieved task status.", + 400: "`invalid_param` : The specified job does not exist.", + }, + ) @service_api_ns.doc("get_annotation_reply_action_status") @service_api_ns.doc(description="Get the status of an annotation reply action job") @service_api_ns.doc(params={"action": "Action type", "job_id": "Job ID"}) @@ -134,6 +158,14 @@ class AnnotationReplyActionStatusApi(Resource): @service_api_ns.route("/apps/annotations") class AnnotationListApi(Resource): + @service_api_ns.doc( + summary="List Annotations", + description="Retrieves a paginated list of annotations for the application. Supports keyword search filtering.", + tags=["Annotations"], + responses={ + 200: "Successfully retrieved annotation list.", + }, + ) @service_api_ns.doc("list_annotations") @service_api_ns.doc(description="List annotations for the application") @service_api_ns.doc(params=query_params_from_model(AnnotationListQuery)) @@ -166,6 +198,17 @@ class AnnotationListApi(Resource): ) return response.model_dump(mode="json") + @service_api_ns.doc( + summary="Create Annotation", + description=( + "Creates a new annotation. Annotations provide predefined question-answer pairs that the app " + "can match and return directly instead of generating a response." + ), + tags=["Annotations"], + responses={ + 201: "Annotation created successfully.", + }, + ) @service_api_ns.expect(service_api_ns.models[AnnotationCreatePayload.__name__]) @service_api_ns.doc("create_annotation") @service_api_ns.doc(description="Create a new annotation") @@ -192,6 +235,16 @@ class AnnotationListApi(Resource): @service_api_ns.route("/apps/annotations/") class AnnotationUpdateDeleteApi(Resource): + @service_api_ns.doc( + summary="Update Annotation", + description="Updates the question and answer of an existing annotation.", + tags=["Annotations"], + responses={ + 200: "Annotation updated successfully.", + 403: "`forbidden` : Insufficient permissions to edit annotations.", + 404: "`not_found` : Annotation does not exist.", + }, + ) @service_api_ns.expect(service_api_ns.models[AnnotationCreatePayload.__name__]) @service_api_ns.doc("update_annotation") @service_api_ns.doc(description="Update an existing annotation") @@ -219,6 +272,16 @@ class AnnotationUpdateDeleteApi(Resource): response = Annotation.model_validate(annotation, from_attributes=True) return response.model_dump(mode="json") + @service_api_ns.doc( + summary="Delete Annotation", + description="Deletes an annotation and its associated hit history.", + tags=["Annotations"], + responses={ + 204: "Annotation deleted successfully.", + 403: "`forbidden` : Insufficient permissions to edit annotations.", + 404: "`not_found` : Annotation does not exist.", + }, + ) @service_api_ns.doc("delete_annotation") @service_api_ns.doc(description="Delete an annotation") @service_api_ns.doc(params={"annotation_id": "Annotation ID"}) diff --git a/api/controllers/service_api/app/app.py b/api/controllers/service_api/app/app.py index cc55876bd5a..d670c7f5a6f 100644 --- a/api/controllers/service_api/app/app.py +++ b/api/controllers/service_api/app/app.py @@ -33,6 +33,18 @@ register_response_schema_models(service_api_ns, Parameters, AppMetaResponse, App class AppParameterApi(Resource): """Resource for app variables.""" + @service_api_ns.doc( + summary="Get App Parameters", + description=( + "Retrieve the application's input form configuration, including feature switches, input " + "parameter names, types, and default values." + ), + tags=["Applications"], + responses={ + 200: "Application parameters information.", + 400: "`app_unavailable` : App unavailable or misconfigured.", + }, + ) @service_api_ns.doc("get_app_parameters") @service_api_ns.doc(description="Retrieve application input parameters and configuration") @service_api_ns.doc( @@ -71,6 +83,14 @@ class AppParameterApi(Resource): @service_api_ns.route("/meta") class AppMetaApi(Resource): + @service_api_ns.doc( + summary="Get App Meta", + description="Retrieve metadata about this application, including tool icons and other configuration details.", + tags=["Applications"], + responses={ + 200: "Successfully retrieved application meta information.", + }, + ) @service_api_ns.doc("get_app_meta") @service_api_ns.doc(description="Get application metadata") @service_api_ns.doc( @@ -92,6 +112,14 @@ class AppMetaApi(Resource): @service_api_ns.route("/info") class AppInfoApi(Resource): + @service_api_ns.doc( + summary="Get App Info", + description="Retrieve basic information about this application, including name, description, tags, and mode.", + tags=["Applications"], + responses={ + 200: "Basic information of the application.", + }, + ) @service_api_ns.doc("get_app_info") @service_api_ns.doc(description="Get basic application information") @service_api_ns.doc( diff --git a/api/controllers/service_api/app/audio.py b/api/controllers/service_api/app/audio.py index ee4109a489b..4bff8e66150 100644 --- a/api/controllers/service_api/app/audio.py +++ b/api/controllers/service_api/app/audio.py @@ -40,6 +40,28 @@ register_response_schema_models(service_api_ns, AudioBinaryResponse, AudioTransc @service_api_ns.route("/audio-to-text") class AudioApi(Resource): + @service_api_ns.doc( + summary="Convert Audio to Text", + description=( + "Convert audio file to text. Supported MIME types: `audio/mp3`, `audio/mpga`, `audio/m4a`, " + "`audio/wav`, and `audio/amr`. File size limit is `30 MB`." + ), + tags=["TTS"], + responses={ + 200: "Successfully converted audio to text.", + 400: ( + "- `app_unavailable` : App unavailable or misconfigured.\n" + "- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n" + "- `provider_not_initialize` : No valid model provider credentials found.\n" + "- `provider_quota_exceeded` : Model provider quota exhausted.\n" + "- `model_currently_not_support` : Current model does not support this operation.\n" + "- `completion_request_error` : Speech recognition request failed." + ), + 413: "`audio_too_large` : Audio file size exceeded the limit.", + 415: "`unsupported_audio_type` : Audio type is not allowed.", + 500: "`internal_server_error` : Internal server error.", + }, + ) @service_api_ns.doc("audio_to_text") @service_api_ns.doc(description="Convert audio to text using speech-to-text") @service_api_ns.doc(consumes=["multipart/form-data"], params=multipart_file_params(include_user=True)) @@ -101,6 +123,25 @@ register_schema_model(service_api_ns, TextToAudioPayload) @service_api_ns.route("/text-to-audio") class TextApi(Resource): + @service_api_ns.doc( + summary="Convert Text to Audio", + description="Convert text to speech.", + tags=["TTS"], + responses={ + 200: ( + "Returns the generated audio. Generator responses are streamed by the service as `audio/mpeg`; " + "otherwise the provider output is returned directly." + ), + 400: ( + "- `app_unavailable` : App unavailable or misconfigured.\n" + "- `provider_not_initialize` : No valid model provider credentials found.\n" + "- `provider_quota_exceeded` : Model provider quota exhausted.\n" + "- `model_currently_not_support` : Current model does not support this operation.\n" + "- `completion_request_error` : Text-to-speech request failed." + ), + 500: "`internal_server_error` : Internal server error.", + }, + ) @expect_with_user(service_api_ns, TextToAudioPayload) @binary_response(service_api_ns, "audio/mpeg") @service_api_ns.doc("text_to_audio") diff --git a/api/controllers/service_api/app/completion.py b/api/controllers/service_api/app/completion.py index d50055dad01..99e7aaecd8c 100644 --- a/api/controllers/service_api/app/completion.py +++ b/api/controllers/service_api/app/completion.py @@ -93,6 +93,31 @@ register_response_schema_models(service_api_ns, GeneratedAppResponse, SimpleResu @service_api_ns.route("/completion-messages") class CompletionApi(Resource): + @service_api_ns.doc( + summary="Send Completion Message", + description="Send a request to the text generation application.", + tags=["Completions"], + responses={ + 200: ( + "Successful response. The content type and structure depend on the `response_mode` parameter " + "in the request.\n" + "\n" + "- If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` " + "object.\n" + "- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of " + "`ChunkCompletionEvent` objects." + ), + 400: ( + "- `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." + ), + 429: "`too_many_requests` : Too many concurrent requests for this app.", + 500: "`internal_server_error` : Internal server error.", + }, + ) @expect_with_user(service_api_ns, CompletionRequestPayload) @json_or_event_stream_response(service_api_ns) @service_api_ns.doc("create_completion") @@ -170,6 +195,14 @@ class CompletionApi(Resource): @service_api_ns.route("/completion-messages//stop") class CompletionStopApi(Resource): + @service_api_ns.doc( + summary="Stop Completion Message Generation", + description="Stops a completion message generation task. Only supported in `streaming` mode.", + tags=["Completions"], + responses={ + 400: "`app_unavailable` : App unavailable or misconfigured.", + }, + ) @expect_user_json(service_api_ns) @service_api_ns.doc("stop_completion") @service_api_ns.doc(description="Stop a running completion task") @@ -200,6 +233,37 @@ class CompletionStopApi(Resource): @service_api_ns.route("/chat-messages") class ChatApi(Resource): + @service_api_ns.doc( + summary="Send Chat Message", + description="Send a request to the chat application.", + tags=["Chats", "Chatflows"], + responses={ + 200: ( + "Successful response. The content type and structure depend on the `response_mode` parameter " + "in the request.\n" + "\n" + "- If `response_mode` is `blocking`, returns `application/json` with a " + "`ChatCompletionResponse` object.\n" + "- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of " + "Server-Sent Events." + ), + 400: ( + "- `app_unavailable` : App unavailable or misconfigured.\n" + "- `not_chat_app` : App mode does not match the API route.\n" + "- `conversation_completed` : The conversation has ended.\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." + ), + 404: "`not_found` : Conversation does not exist.", + 429: ( + "- `too_many_requests` : Too many concurrent requests for this app.\n" + "- `rate_limit_error` : The upstream model provider rate limit was exceeded." + ), + 500: "`internal_server_error` : Internal server error.", + }, + ) @expect_with_user(service_api_ns, ChatRequestPayload) @json_or_event_stream_response(service_api_ns) @service_api_ns.doc("create_chat_message") @@ -280,6 +344,14 @@ class ChatApi(Resource): @service_api_ns.route("/chat-messages//stop") class ChatStopApi(Resource): + @service_api_ns.doc( + summary="Stop Chat Message Generation", + description="Stops a chat message generation task. Only supported in `streaming` mode.", + tags=["Chats", "Chatflows"], + responses={ + 400: "`not_chat_app` : App mode does not match the API route.", + }, + ) @expect_user_json(service_api_ns) @service_api_ns.doc("stop_chat_message") @service_api_ns.doc(description="Stop a running chat message generation") diff --git a/api/controllers/service_api/app/conversation.py b/api/controllers/service_api/app/conversation.py index f3af251de50..a208c8fee49 100644 --- a/api/controllers/service_api/app/conversation.py +++ b/api/controllers/service_api/app/conversation.py @@ -146,6 +146,16 @@ register_response_schema_models( @service_api_ns.route("/conversations") class ConversationApi(Resource): + @service_api_ns.doc( + summary="List Conversations", + description="Retrieve the conversation list for the current user, ordered by most recently active.", + tags=["Conversations"], + responses={ + 200: "Successfully retrieved conversations list.", + 400: "`not_chat_app` : App mode does not match the API route.", + 404: "`not_found` : Last conversation does not exist (invalid `last_id`).", + }, + ) @service_api_ns.doc(params=query_params_from_model(ConversationListQuery)) @service_api_ns.doc("list_conversations") @service_api_ns.doc(description="List all conversations for the current user") @@ -198,6 +208,16 @@ class ConversationApi(Resource): @service_api_ns.route("/conversations/") class ConversationDetailApi(Resource): + @service_api_ns.doc( + summary="Delete Conversation", + description="Delete a conversation.", + tags=["Conversations"], + responses={ + 204: "Conversation deleted successfully.", + 400: "`not_chat_app` : App mode does not match the API route.", + 404: "`not_found` : Conversation does not exist.", + }, + ) @expect_user_json(service_api_ns) @service_api_ns.doc("delete_conversation") @service_api_ns.doc(description="Delete a specific conversation") @@ -227,6 +247,19 @@ class ConversationDetailApi(Resource): @service_api_ns.route("/conversations//name") class ConversationRenameApi(Resource): + @service_api_ns.doc( + summary="Rename Conversation", + description=( + "Rename a conversation or auto-generate a name. The conversation name is used for display on " + "clients that support multiple conversations." + ), + tags=["Conversations"], + responses={ + 200: "Conversation renamed successfully.", + 400: "`not_chat_app` : App mode does not match the API route.", + 404: "`not_found` : Conversation does not exist.", + }, + ) @expect_with_user(service_api_ns, ConversationRenamePayload) @service_api_ns.doc("rename_conversation") @service_api_ns.doc(description="Rename a conversation or auto-generate a name") @@ -269,6 +302,16 @@ class ConversationRenameApi(Resource): @service_api_ns.route("/conversations//variables") class ConversationVariablesApi(Resource): + @service_api_ns.doc( + summary="List Conversation Variables", + description="Retrieve variables from a specific conversation.", + tags=["Conversations"], + responses={ + 200: "Successfully retrieved conversation variables.", + 400: "`not_chat_app` : App mode does not match the API route.", + 404: "`not_found` : Conversation does not exist.", + }, + ) @service_api_ns.doc(params=query_params_from_model(ConversationVariablesQuery)) @service_api_ns.doc("list_conversation_variables") @service_api_ns.doc(description="List all variables for a conversation") @@ -314,6 +357,21 @@ class ConversationVariablesApi(Resource): @service_api_ns.route("/conversations//variables/") class ConversationVariableDetailApi(Resource): + @service_api_ns.doc( + summary="Update Conversation Variable", + description="Update the value of a specific conversation variable. The value must match the expected type.", + tags=["Conversations"], + responses={ + 200: "Variable updated successfully.", + 400: ( + "- `not_chat_app` : App mode does not match the API route.\n" + "- `bad_request` : Variable value type mismatch." + ), + 404: ( + "- `not_found` : Conversation does not exist.\n- `not_found` : Conversation variable does not exist." + ), + }, + ) @expect_with_user(service_api_ns, ConversationVariableUpdatePayload) @service_api_ns.doc("update_conversation_variable") @service_api_ns.doc(description="Update a conversation variable's value") diff --git a/api/controllers/service_api/app/file.py b/api/controllers/service_api/app/file.py index 38ec064c769..9210c60adeb 100644 --- a/api/controllers/service_api/app/file.py +++ b/api/controllers/service_api/app/file.py @@ -24,6 +24,24 @@ register_schema_models(service_api_ns, FileResponse) @service_api_ns.route("/files/upload") class FileApi(Resource): + @service_api_ns.doc( + summary="Upload File", + description=( + "Upload a file for use when sending messages, enabling multimodal understanding of images, " + "documents, audio, and video. Uploaded files are for use by the current end-user only." + ), + tags=["Files"], + responses={ + 201: "File uploaded successfully.", + 400: ( + "- `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." + ), + 413: "`file_too_large` : File size exceeded.", + 415: "`unsupported_file_type` : File type not allowed.", + }, + ) @service_api_ns.doc("upload_file") @service_api_ns.doc(description="Upload a file for use in conversations") @service_api_ns.doc(consumes=["multipart/form-data"], params=multipart_file_params(include_user=True)) diff --git a/api/controllers/service_api/app/file_preview.py b/api/controllers/service_api/app/file_preview.py index bcf09660f12..0b7e057152b 100644 --- a/api/controllers/service_api/app/file_preview.py +++ b/api/controllers/service_api/app/file_preview.py @@ -61,6 +61,24 @@ class FilePreviewApi(Resource): Files can only be accessed if they belong to messages within the requesting app's context. """ + @service_api_ns.doc( + summary="Download File", + description=( + "Preview or download uploaded files previously uploaded via the [Upload " + "File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to " + "messages within the requesting application." + ), + tags=["Files"], + responses={ + 200: ( + "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If " + "`as_attachment` is `true`, the file is returned as a download with `Content-Disposition: " + "attachment`." + ), + 403: "`file_access_denied` : Access to the requested file is denied.", + 404: "`file_not_found` : The requested file was not found.", + }, + ) @service_api_ns.doc(params=query_params_from_model(FilePreviewQuery)) @binary_response(service_api_ns, FILE_PREVIEW_RESPONSE_MEDIA_TYPES) @service_api_ns.doc("preview_file") diff --git a/api/controllers/service_api/app/human_input_form.py b/api/controllers/service_api/app/human_input_form.py index 3c43625d6ad..07cc1eeab6d 100644 --- a/api/controllers/service_api/app/human_input_form.py +++ b/api/controllers/service_api/app/human_input_form.py @@ -73,6 +73,23 @@ def _ensure_form_is_allowed_for_service_api(form: Form) -> None: @service_api_ns.route("/form/human_input/") class WorkflowHumanInputFormApi(Resource): + @service_api_ns.doc( + summary="Get Human Input Form", + description=( + "Retrieve a paused Human Input form's contents using the `form_token` from a " + "`human_input_required` event. Requires **WebApp** delivery." + ), + tags=["Human Input"], + responses={ + 200: "Form contents retrieved successfully.", + 404: "`not_found` : Form not found.", + 412: ( + "- `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." + ), + }, + ) @service_api_ns.doc("get_human_input_form") @service_api_ns.doc(description="Get a paused human input form by token") @service_api_ns.doc(params={"form_token": "Human input form token"}) @@ -102,6 +119,28 @@ class WorkflowHumanInputFormApi(Resource): inputs = service.resolve_form_inputs(form) return _jsonify_form_definition(form, inputs=inputs) + @service_api_ns.doc( + summary="Submit Human Input Form", + description=( + "Submit the recipient's response to a paused Human Input form. The workflow resumes on " + "acceptance; use [Stream Workflow Events](/api-reference/chatflows/stream-workflow-events) " + "to follow subsequent events. Requires **WebApp** delivery." + ), + tags=["Human Input"], + responses={ + 200: "Form submitted successfully. The response body is an empty object.", + 400: ( + "- `bad_request` : Form recipient type is invalid.\n" + "- `invalid_form_data` : Submission failed validation against the form definition." + ), + 404: "`not_found` : Form not found.", + 412: ( + "- `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." + ), + }, + ) @expect_with_user(service_api_ns, HumanInputFormSubmitPayload) @service_api_ns.doc("submit_human_input_form") @service_api_ns.doc(description="Submit a paused human input form by token") diff --git a/api/controllers/service_api/app/message.py b/api/controllers/service_api/app/message.py index e1d1c61d372..a51daf7973d 100644 --- a/api/controllers/service_api/app/message.py +++ b/api/controllers/service_api/app/message.py @@ -65,6 +65,19 @@ register_response_schema_models( @service_api_ns.route("/messages") class MessageListApi(Resource): + @service_api_ns.doc( + summary="List Conversation Messages", + description=( + "Returns historical chat records in a scrolling load format, with the first page returning " + "the latest `limit` messages, i.e., in reverse order." + ), + tags=["Conversations"], + responses={ + 200: "Successfully retrieved conversation history.", + 400: "`not_chat_app` : App mode does not match the API route.", + 404: ("- `not_found` : Conversation does not exist.\n- `not_found` : First message does not exist."), + }, + ) @service_api_ns.doc(params=query_params_from_model(MessageListQuery)) @service_api_ns.doc("list_messages") @service_api_ns.doc(description="List messages in a conversation") @@ -113,6 +126,18 @@ class MessageListApi(Resource): @service_api_ns.route("/messages//feedbacks") class MessageFeedbackApi(Resource): + @service_api_ns.doc( + summary="Submit Message Feedback", + description=( + "Submit feedback for a message. End users can rate messages as `like` or `dislike`, and " + "optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted " + "feedback." + ), + tags=["Feedback"], + responses={ + 404: "`not_found` : Message does not exist.", + }, + ) @expect_with_user(service_api_ns, MessageFeedbackPayload) @service_api_ns.response(200, "Feedback submitted successfully", service_api_ns.models[ResultResponse.__name__]) @service_api_ns.doc("create_message_feedback") @@ -151,6 +176,17 @@ class MessageFeedbackApi(Resource): @service_api_ns.route("/app/feedbacks") class AppGetFeedbacksApi(Resource): + @service_api_ns.doc( + summary="List App Feedbacks", + description=( + "Retrieve a paginated list of all feedback submitted for messages in this application, " + "including both end-user and admin feedback." + ), + tags=["Feedback"], + responses={ + 200: "A list of application feedbacks.", + }, + ) @service_api_ns.doc(params=query_params_from_model(FeedbackListQuery)) @service_api_ns.doc("get_app_feedbacks") @service_api_ns.doc(description="Get all feedbacks for the application") @@ -178,6 +214,20 @@ class AppGetFeedbacksApi(Resource): @service_api_ns.route("/messages//suggested") class MessageSuggestedApi(Resource): + @service_api_ns.doc( + summary="Get Next Suggested Questions", + description="Get next questions suggestions for the current message.", + tags=["Chats", "Chatflows"], + responses={ + 200: "Successfully retrieved suggested questions.", + 400: ( + "- `not_chat_app` : App mode does not match the API route.\n" + "- `bad_request` : Suggested questions feature is disabled." + ), + 404: "`not_found` : Message does not exist.", + 500: "`internal_server_error` : Internal server error.", + }, + ) @service_api_ns.response( 200, "Suggested questions retrieved successfully", diff --git a/api/controllers/service_api/app/site.py b/api/controllers/service_api/app/site.py index f5d1dcd283d..35098ca1367 100644 --- a/api/controllers/service_api/app/site.py +++ b/api/controllers/service_api/app/site.py @@ -17,6 +17,18 @@ register_response_schema_models(service_api_ns, SiteResponse) class AppSiteApi(Resource): """Resource for app sites.""" + @service_api_ns.doc( + summary="Get App WebApp Settings", + description=( + "Retrieve the WebApp settings of this application, including site configuration, theme, and " + "customization options." + ), + tags=["Applications"], + responses={ + 200: "WebApp settings of the application.", + 403: "`forbidden` : Site not found for this application or the workspace has been archived.", + }, + ) @service_api_ns.doc("get_app_site") @service_api_ns.doc(description="Get application site configuration") @service_api_ns.doc( diff --git a/api/controllers/service_api/app/workflow.py b/api/controllers/service_api/app/workflow.py index db7f7271764..83442b316f9 100644 --- a/api/controllers/service_api/app/workflow.py +++ b/api/controllers/service_api/app/workflow.py @@ -213,6 +213,16 @@ def _serialize_workflow_log_pagination(pagination) -> dict: @service_api_ns.route("/workflows/run/") class WorkflowRunDetailApi(Resource): + @service_api_ns.doc( + summary="Get Workflow Run Detail", + description="Retrieve the current execution results of a workflow task based on the workflow execution ID.", + tags=["Chatflows", "Workflows"], + responses={ + 200: "Successfully retrieved workflow run details.", + 400: "`not_workflow_app` : App mode does not match the API route.", + 404: "`not_found` : Workflow run not found.", + }, + ) @service_api_ns.doc("get_workflow_run_detail") @service_api_ns.doc(description="Get workflow run details") @service_api_ns.doc(params={"workflow_run_id": "Workflow run ID"}) @@ -254,6 +264,35 @@ class WorkflowRunDetailApi(Resource): @service_api_ns.route("/workflows/run") class WorkflowRunApi(Resource): + @service_api_ns.doc( + summary="Run Workflow", + description="Execute a workflow. Cannot be executed without a published workflow.", + tags=["Workflows"], + responses={ + 200: ( + "Successful response. The content type and structure depend on the `response_mode` parameter " + "in the request.\n" + "\n" + "- If `response_mode` is `blocking`, returns `application/json` with a " + "`WorkflowBlockingResponse` object.\n" + "- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of " + "`ChunkWorkflowEvent` objects." + ), + 400: ( + "- `not_workflow_app` : App mode does not match the API route.\n" + "- `provider_not_initialize` : No valid model provider credentials found.\n" + "- `provider_quota_exceeded` : Model provider quota exhausted.\n" + "- `model_currently_not_support` : Current model unavailable.\n" + "- `completion_request_error` : Workflow execution request failed.\n" + "- `invalid_param` : Invalid parameter value." + ), + 429: ( + "- `too_many_requests` : Too many concurrent requests for this app.\n" + "- `rate_limit_error` : The upstream model provider rate limit was exceeded." + ), + 500: "`internal_server_error` : Internal server error.", + }, + ) @expect_with_user(service_api_ns, WorkflowRunPayload) @json_or_event_stream_response(service_api_ns) @service_api_ns.doc("run_workflow") @@ -319,6 +358,40 @@ class WorkflowRunApi(Resource): @service_api_ns.route("/workflows//run") class WorkflowRunByIdApi(Resource): + @service_api_ns.doc( + summary="Run Workflow by ID", + description=( + "Execute a specific workflow version identified by its ID. Useful for running a particular " + "published version of the workflow." + ), + tags=["Workflows"], + responses={ + 200: ( + "Successful response. The content type and structure depend on the `response_mode` parameter " + "in the request.\n" + "\n" + "- If `response_mode` is `blocking`, returns `application/json` with a " + "`WorkflowBlockingResponse` object.\n" + "- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of " + "`ChunkWorkflowEvent` objects." + ), + 400: ( + "- `not_workflow_app` : App mode does not match the API route.\n" + "- `bad_request` : Workflow is a draft or has an invalid ID format.\n" + "- `provider_not_initialize` : No valid model provider credentials found.\n" + "- `provider_quota_exceeded` : Model provider quota exhausted.\n" + "- `model_currently_not_support` : Current model unavailable.\n" + "- `completion_request_error` : Workflow execution request failed.\n" + "- `invalid_param` : Required parameter missing or invalid." + ), + 404: "`not_found` : Workflow not found.", + 429: ( + "- `too_many_requests` : Too many concurrent requests for this app.\n" + "- `rate_limit_error` : The upstream model provider rate limit was exceeded." + ), + 500: "`internal_server_error` : Internal server error.", + }, + ) @expect_with_user(service_api_ns, WorkflowRunPayload) @json_or_event_stream_response(service_api_ns) @service_api_ns.doc("run_workflow_by_id") @@ -394,6 +467,17 @@ class WorkflowRunByIdApi(Resource): @service_api_ns.route("/workflows/tasks//stop") class WorkflowTaskStopApi(Resource): + @service_api_ns.doc( + summary="Stop Workflow Task", + description="Stop a running workflow task. Only supported in `streaming` mode.", + tags=["Workflows"], + responses={ + 400: ( + "- `not_workflow_app` : App mode does not match the API route.\n" + "- `invalid_param` : Required parameter missing or invalid." + ), + }, + ) @expect_user_json(service_api_ns) @service_api_ns.doc("stop_workflow_task") @service_api_ns.doc(description="Stop a running workflow task") @@ -425,6 +509,14 @@ class WorkflowTaskStopApi(Resource): @service_api_ns.route("/workflows/logs") class WorkflowAppLogApi(Resource): + @service_api_ns.doc( + summary="List Workflow Logs", + description="Retrieve paginated workflow execution logs with filtering options.", + tags=["Chatflows", "Workflows"], + responses={ + 200: "Successfully retrieved workflow logs.", + }, + ) @service_api_ns.doc(params=query_params_from_model(WorkflowLogQuery)) @service_api_ns.doc("get_workflow_logs") @service_api_ns.doc(description="Get workflow execution logs") diff --git a/api/controllers/service_api/app/workflow_events.py b/api/controllers/service_api/app/workflow_events.py index 7445da74860..1bace170f53 100644 --- a/api/controllers/service_api/app/workflow_events.py +++ b/api/controllers/service_api/app/workflow_events.py @@ -45,6 +45,23 @@ register_response_schema_model(service_api_ns, EventStreamResponse) class WorkflowEventsApi(Resource): """Service API for getting workflow execution events after resume.""" + @service_api_ns.doc( + summary="Stream Workflow Events", + description=( + "Resume 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." + ), + tags=["Chatflows", "Workflows"], + responses={ + 200: ( + "Server-Sent Events stream. Each event is delivered as `data: {JSON}\\n\\n`. Event payloads " + "follow the same schemas as the original streaming response." + ), + 400: "`not_workflow_app` : Please check if your app mode matches the right API route.", + 404: "`not_found` : Workflow run not found.", + }, + ) @event_stream_response(service_api_ns) @service_api_ns.doc("get_workflow_events") @service_api_ns.doc(description="Get workflow execution events stream after resume") diff --git a/api/controllers/service_api/dataset/dataset.py b/api/controllers/service_api/dataset/dataset.py index 594ef2393fb..305acae4a6e 100644 --- a/api/controllers/service_api/dataset/dataset.py +++ b/api/controllers/service_api/dataset/dataset.py @@ -250,6 +250,14 @@ register_response_schema_models( class DatasetListApi(DatasetApiResource): """Resource for datasets.""" + @service_api_ns.doc( + summary="List Knowledge Bases", + description="Returns a paginated list of knowledge bases. Supports filtering by keyword and tags.", + tags=["Knowledge Bases"], + responses={ + 200: "List of knowledge bases.", + }, + ) @service_api_ns.doc("list_datasets") @service_api_ns.doc(description="List all datasets") @service_api_ns.doc( @@ -308,6 +316,19 @@ class DatasetListApi(DatasetApiResource): } return dump_response(DatasetListResponse, response), 200 + @service_api_ns.doc( + summary="Create an Empty Knowledge Base", + description=( + "Create a new empty knowledge base. After creation, use [Create Document by " + "Text](/api-reference/documents/create-document-by-text) or [Create Document by " + "File](/api-reference/documents/create-document-by-file) to add documents." + ), + tags=["Knowledge Bases"], + responses={ + 200: "Knowledge base created successfully.", + 409: "`dataset_name_duplicate` : The dataset name already exists. Please modify your dataset name.", + }, + ) @service_api_ns.expect(service_api_ns.models[DatasetCreatePayload.__name__]) @service_api_ns.doc("create_dataset") @service_api_ns.doc(description="Create a new dataset") @@ -373,6 +394,19 @@ class DatasetListApi(DatasetApiResource): class DatasetApi(DatasetApiResource): """Resource for dataset.""" + @service_api_ns.doc( + summary="Get Knowledge Base", + description=( + "Retrieve detailed information about a specific knowledge base, including its embedding " + "model, retrieval configuration, and document statistics." + ), + tags=["Knowledge Bases"], + responses={ + 200: "Knowledge base details.", + 403: "`forbidden` : Insufficient permissions to access this knowledge base.", + 404: "`not_found` : Dataset not found.", + }, + ) @service_api_ns.doc("get_dataset") @service_api_ns.doc(description="Get a specific dataset by ID") @service_api_ns.doc(params={"dataset_id": "Dataset ID"}) @@ -438,6 +472,19 @@ class DatasetApi(DatasetApiResource): 200, ) + @service_api_ns.doc( + summary="Update Knowledge Base", + description=( + "Update the name, description, permissions, or retrieval settings of an existing knowledge " + "base. Only the fields provided in the request body are updated." + ), + tags=["Knowledge Bases"], + responses={ + 200: "Knowledge base updated successfully.", + 403: "`forbidden` : Insufficient permissions to access this knowledge base.", + 404: "`not_found` : Dataset not found.", + }, + ) @service_api_ns.expect(service_api_ns.models[DatasetUpdatePayload.__name__]) @service_api_ns.doc("update_dataset") @service_api_ns.doc(description="Update an existing dataset") @@ -520,6 +567,22 @@ class DatasetApi(DatasetApiResource): return DatasetDetailWithPartialMembersResponse.model_validate(result_data).model_dump(mode="json"), 200 + @service_api_ns.doc( + summary="Delete Knowledge Base", + description=( + "Permanently delete a knowledge base and all its documents. The knowledge base must not be " + "in use by any application." + ), + tags=["Knowledge Bases"], + responses={ + 204: "Success.", + 404: "`not_found` : Dataset not found.", + 409: ( + "`dataset_in_use` : The knowledge base is being used by some apps. Please remove it from the " + "apps before deleting." + ), + }, + ) @service_api_ns.doc("delete_dataset") @service_api_ns.doc(description="Delete a dataset") @service_api_ns.doc(params={"dataset_id": "Dataset ID"}) @@ -565,6 +628,17 @@ class DatasetApi(DatasetApiResource): class DocumentStatusApi(DatasetApiResource): """Resource for batch document status operations.""" + @service_api_ns.doc( + summary="Update Document Status in Batch", + description="Enable, disable, archive, or unarchive multiple documents at once.", + tags=["Documents"], + responses={ + 200: "Documents updated successfully.", + 400: "`invalid_action` : Invalid action.", + 403: "`forbidden` : Insufficient permissions.", + 404: "`not_found` : Knowledge base not found.", + }, + ) @service_api_ns.response( 200, "Document status updated successfully", @@ -637,6 +711,14 @@ class DocumentStatusApi(DatasetApiResource): @service_api_ns.route("/datasets/tags") class DatasetTagsApi(DatasetApiResource): + @service_api_ns.doc( + summary="List Knowledge Tags", + description="Returns the list of all knowledge base tags in the workspace.", + tags=["Tags"], + responses={ + 200: "List of tags.", + }, + ) @service_api_ns.doc("list_dataset_tags") @service_api_ns.doc(description="Get all knowledge type tags") @service_api_ns.doc( @@ -658,6 +740,14 @@ class DatasetTagsApi(DatasetApiResource): tags = TagService.get_tags(db.session(), "knowledge", cid) return dump_response(KnowledgeTagListResponse, tags), 200 + @service_api_ns.doc( + summary="Create Knowledge Tag", + description="Create a new tag for organizing knowledge bases.", + tags=["Tags"], + responses={ + 200: "Tag created successfully.", + }, + ) @service_api_ns.expect(service_api_ns.models[TagCreatePayload.__name__]) @service_api_ns.doc("create_dataset_tag") @service_api_ns.doc(description="Add a knowledge type tag") @@ -688,6 +778,14 @@ class DatasetTagsApi(DatasetApiResource): ) return response, 200 + @service_api_ns.doc( + summary="Update Knowledge Tag", + description="Rename an existing knowledge base tag.", + tags=["Tags"], + responses={ + 200: "Tag updated successfully.", + }, + ) @service_api_ns.expect(service_api_ns.models[TagUpdatePayload.__name__]) @service_api_ns.doc("update_dataset_tag") @service_api_ns.doc(description="Update a knowledge type tag") @@ -720,6 +818,14 @@ class DatasetTagsApi(DatasetApiResource): ) return response, 200 + @service_api_ns.doc( + summary="Delete Knowledge Tag", + description="Permanently delete a knowledge base tag. Does not delete the knowledge bases that were tagged.", + tags=["Tags"], + responses={ + 204: "Success.", + }, + ) @service_api_ns.expect(service_api_ns.models[TagDeletePayload.__name__]) @service_api_ns.doc("delete_dataset_tag") @service_api_ns.doc(description="Delete a knowledge type tag") @@ -741,6 +847,14 @@ class DatasetTagsApi(DatasetApiResource): @service_api_ns.route("/datasets/tags/binding") class DatasetTagBindingApi(DatasetApiResource): + @service_api_ns.doc( + summary="Create Tag Binding", + description="Bind one or more tags to a knowledge base. A knowledge base can have multiple tags.", + tags=["Tags"], + responses={ + 204: "Success.", + }, + ) @service_api_ns.expect(service_api_ns.models[TagBindingPayload.__name__]) @service_api_ns.doc("bind_dataset_tags") @service_api_ns.doc(description="Bind tags to a dataset") @@ -767,6 +881,14 @@ class DatasetTagBindingApi(DatasetApiResource): @service_api_ns.route("/datasets/tags/unbinding") class DatasetTagUnbindingApi(DatasetApiResource): + @service_api_ns.doc( + summary="Delete Tag Binding", + description="Remove one or more tags from a knowledge base.", + tags=["Tags"], + responses={ + 204: "Success.", + }, + ) @service_api_ns.expect(service_api_ns.models[TagUnbindingPayload.__name__]) @service_api_ns.doc("unbind_dataset_tags") @service_api_ns.doc(description="Unbind tags from a dataset") @@ -793,6 +915,14 @@ class DatasetTagUnbindingApi(DatasetApiResource): @service_api_ns.route("/datasets//tags") class DatasetTagsBindingStatusApi(DatasetApiResource): + @service_api_ns.doc( + summary="Get Knowledge Base Tags", + description="Returns the list of tags bound to a specific knowledge base.", + tags=["Tags"], + responses={ + 200: "Tags bound to the knowledge base.", + }, + ) @service_api_ns.doc("get_dataset_tags_binding_status") @service_api_ns.doc(description="Get tags bound to a specific dataset") @service_api_ns.doc(params={"dataset_id": "Dataset ID"}) diff --git a/api/controllers/service_api/dataset/document.py b/api/controllers/service_api/dataset/document.py index ca49bb6bc57..871c5e888b1 100644 --- a/api/controllers/service_api/dataset/document.py +++ b/api/controllers/service_api/dataset/document.py @@ -401,6 +401,24 @@ def _update_document_by_text(tenant_id: str, dataset_id: UUID, document_id: UUID class DocumentAddByTextApi(DatasetApiResource): """Resource for the canonical text document creation route.""" + @service_api_ns.doc( + summary="Create Document by Text", + description=( + "Create a document from raw text content. The document is processed asynchronously — use the " + "returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/" + "get-document-indexing-status) to track progress." + ), + tags=["Documents"], + responses={ + 200: "Document created successfully.", + 400: ( + "- `provider_not_initialize` : No valid model provider credentials found. Please go to " + "Settings -> Model Provider to complete your provider credentials.\n" + "- `invalid_param` : Knowledge base does not exist. / indexing_technique is required. / " + "Invalid doc_form (must be `text_model`, `hierarchical_model`, or `qa_model`)." + ), + }, + ) @service_api_ns.expect(service_api_ns.models[DocumentTextCreatePayload.__name__]) @service_api_ns.doc("create_document_by_text") @service_api_ns.doc(description="Create a new document by providing text content") @@ -459,6 +477,25 @@ class DeprecatedDocumentAddByTextApi(DatasetApiResource): class DocumentUpdateByTextApi(DatasetApiResource): """Resource for the canonical text document update route.""" + @service_api_ns.doc( + summary="Update Document by Text", + description=( + "Update an existing document's text content, name, or processing configuration. Re-triggers " + "indexing if content changes — use the returned `batch` ID with [Get Document Indexing " + "Status](/api-reference/documents/get-document-indexing-status) to track progress." + ), + tags=["Documents"], + responses={ + 200: "Document updated successfully.", + 400: ( + "- `provider_not_initialize` : No valid model provider credentials found. Please go to " + "Settings -> Model Provider to complete your provider credentials.\n" + "- `invalid_param` : Knowledge base does not exist, name is required when text is " + "provided, or invalid doc_form (must be `text_model`, `hierarchical_model`, or " + "`qa_model`)." + ), + }, + ) @service_api_ns.expect(service_api_ns.models[DocumentTextUpdate.__name__]) @service_api_ns.doc("update_document_by_text") @service_api_ns.doc(description="Update an existing document by providing text content") @@ -527,6 +564,28 @@ class DeprecatedDocumentUpdateByTextApi(DatasetApiResource): class DocumentAddByFileApi(DatasetApiResource): """Resource for documents.""" + @service_api_ns.doc( + summary="Create Document by File", + description=( + "Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, " + "etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document " + "Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress." + ), + tags=["Documents"], + responses={ + 200: "Document created successfully.", + 400: ( + "- `no_file_uploaded` : Please upload your file.\n" + "- `too_many_files` : Only one file is allowed.\n" + "- `filename_not_exists_error` : The specified filename does not exist.\n" + "- `provider_not_initialize` : No valid model provider credentials found. Please go to " + "Settings -> Model Provider to complete your provider credentials.\n" + "- `invalid_param` : Knowledge base does not exist, external datasets not supported, " + "file too large, unsupported file type, missing required fields, or invalid doc_form " + "(must be `text_model`, `hierarchical_model`, or `qa_model`)." + ), + }, + ) @service_api_ns.doc("create_document_by_file") @service_api_ns.doc(description="Create a new document by uploading a file") @service_api_ns.doc(consumes=["multipart/form-data"], params=DOCUMENT_CREATE_BY_FILE_PARAMS) @@ -717,6 +776,27 @@ def _update_document_by_file(tenant_id: str, dataset_id: UUID, document_id: UUID class DeprecatedDocumentUpdateByFileApi(DatasetApiResource): """Deprecated resource aliases for file document updates.""" + @service_api_ns.doc( + summary="Update Document by File", + description=( + "Update an existing document by uploading a new file. Re-triggers indexing — use the returned " + "`batch` ID with [Get Document Indexing Status](/api-reference/documents/" + "get-document-indexing-status) to track progress." + ), + tags=["Documents"], + responses={ + 200: "Document updated successfully.", + 400: ( + "- `too_many_files` : Only one file is allowed.\n" + "- `filename_not_exists_error` : The specified filename does not exist.\n" + "- `provider_not_initialize` : No valid model provider credentials found. Please go to " + "Settings -> Model Provider to complete your provider credentials.\n" + "- `invalid_param` : Knowledge base does not exist, external datasets not supported, " + "file too large, unsupported file type, or invalid doc_form (must be `text_model`, " + "`hierarchical_model`, or `qa_model`)." + ), + }, + ) @service_api_ns.doc("update_document_by_file_deprecated") @service_api_ns.doc(deprecated=True) @service_api_ns.doc( @@ -745,6 +825,18 @@ class DeprecatedDocumentUpdateByFileApi(DatasetApiResource): @service_api_ns.route("/datasets//documents") class DocumentListApi(DatasetApiResource): + @service_api_ns.doc( + summary="List Documents", + description=( + "Returns a paginated list of documents in the knowledge base. Supports filtering by keyword " + "and indexing status." + ), + tags=["Documents"], + responses={ + 200: "List of documents.", + 404: "`not_found` : Knowledge base not found.", + }, + ) @service_api_ns.doc("list_documents") @service_api_ns.doc(description="List all documents in a dataset") @service_api_ns.doc(params={"dataset_id": "Dataset ID", **query_params_from_model(DocumentListQuery)}) @@ -805,6 +897,18 @@ class DocumentListApi(DatasetApiResource): class DocumentBatchDownloadZipApi(DatasetApiResource): """Download multiple uploaded-file documents as a single ZIP archive.""" + @service_api_ns.doc( + summary="Download Documents as ZIP", + description=( + "Download multiple uploaded-file documents as a single ZIP archive. Accepts up to `100` document IDs." + ), + tags=["Documents"], + responses={ + 200: "ZIP archive containing the requested documents.", + 403: "`forbidden` : Insufficient permissions.", + 404: "`not_found` : Document or dataset not found.", + }, + ) @binary_response(service_api_ns, "application/zip") @service_api_ns.expect(service_api_ns.models[DocumentBatchDownloadZipPayload.__name__]) @service_api_ns.doc("download_documents_as_zip") @@ -845,6 +949,20 @@ class DocumentBatchDownloadZipApi(DatasetApiResource): @service_api_ns.route("/datasets//documents//indexing-status") class DocumentIndexingStatusApi(DatasetApiResource): + @service_api_ns.doc( + summary="Get Document Indexing Status", + description=( + "Check the indexing progress of documents in a batch. Returns the current processing stage " + "and chunk completion counts for each document. Poll this endpoint until `indexing_status` " + "reaches `completed` or `error`. The status progresses through: `waiting` → `parsing` → " + "`cleaning` → `splitting` → `indexing` → `completed`." + ), + tags=["Documents"], + responses={ + 200: "Indexing status for documents in the batch.", + 404: "`not_found` : Knowledge base not found. / Documents not found.", + }, + ) @service_api_ns.doc("get_document_indexing_status") @service_api_ns.doc(description="Get indexing status for documents in a batch") @service_api_ns.doc(params={"dataset_id": "Dataset ID", "batch": "Batch ID"}) @@ -917,6 +1035,16 @@ class DocumentIndexingStatusApi(DatasetApiResource): class DocumentDownloadApi(DatasetApiResource): """Return a signed download URL for a document's original uploaded file.""" + @service_api_ns.doc( + summary="Download Document", + description="Get a signed download URL for a document's original uploaded file.", + tags=["Documents"], + responses={ + 200: "Download URL generated successfully.", + 403: "`forbidden` : No permission to access this document.", + 404: "`not_found` : Document not found.", + }, + ) @service_api_ns.doc("get_document_download_url") @service_api_ns.doc(description="Get a signed download URL for a document's original uploaded file") @service_api_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"}) @@ -951,6 +1079,24 @@ class DocumentDownloadApi(DatasetApiResource): class DocumentApi(DatasetApiResource): METADATA_CHOICES = {"all", "only", "without"} + @service_api_ns.doc( + summary="Get Document", + description=( + "Retrieve detailed information about a specific document, including its indexing status, " + "metadata, and processing statistics." + ), + tags=["Documents"], + responses={ + 200: ( + "Document details. The response shape varies based on the `metadata` query parameter. When " + "`metadata` is `only`, only `id`, `doc_type`, and `doc_metadata` are returned. When " + "`metadata` is `without`, `doc_type` and `doc_metadata` are omitted." + ), + 400: "`invalid_metadata` : Invalid metadata value for the specified key.", + 403: "`forbidden` : No permission.", + 404: "`not_found` : Document not found.", + }, + ) @service_api_ns.doc("get_document") @service_api_ns.doc(description="Get a specific document by ID") @service_api_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"}) @@ -1092,6 +1238,17 @@ class DocumentApi(DatasetApiResource): """Update document by file on the canonical document resource.""" return _update_document_by_file(tenant_id=tenant_id, dataset_id=dataset_id, document_id=document_id) + @service_api_ns.doc( + summary="Delete Document", + description="Permanently delete a document and all its chunks from the knowledge base.", + tags=["Documents"], + responses={ + 204: "Success.", + 400: "`document_indexing` : Cannot delete document during indexing.", + 403: "`archived_document_immutable` : The archived document is not editable.", + 404: "`not_found` : Document Not Exists.", + }, + ) @service_api_ns.doc("delete_document") @service_api_ns.doc(description="Delete a document") @service_api_ns.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"}) diff --git a/api/controllers/service_api/dataset/hit_testing.py b/api/controllers/service_api/dataset/hit_testing.py index 55a1c47c425..fb55b18059d 100644 --- a/api/controllers/service_api/dataset/hit_testing.py +++ b/api/controllers/service_api/dataset/hit_testing.py @@ -13,6 +13,32 @@ register_response_schema_models(service_api_ns, HitTestingResponse) @service_api_ns.route("/datasets//hit-testing", "/datasets//retrieve") class HitTestingApi(DatasetApiResource, DatasetsHitTestingBase): + @service_api_ns.doc( + summary="Retrieve Chunks from a Knowledge Base / Test Retrieval", + description=( + "Performs a search query against a knowledge base to retrieve the most relevant chunks. This " + "endpoint can be used for both production retrieval and test retrieval." + ), + tags=["Knowledge Bases"], + responses={ + 200: "Retrieval results.", + 400: ( + "- `dataset_not_initialized` : The dataset is still being initialized or indexing. Please " + "wait a moment.\n" + "- `provider_not_initialize` : No valid model provider credentials found. Please go to " + "Settings -> Model Provider to complete your provider credentials.\n" + "- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please " + "go to Settings -> Model Provider to complete your own provider credentials.\n" + "- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 " + "model.\n" + "- `completion_request_error` : Completion request failed.\n" + "- `invalid_param` : Invalid parameter value." + ), + 403: "`forbidden` : Insufficient permissions.", + 404: "`not_found` : Knowledge base not found.", + 500: "`internal_server_error` : An internal error occurred during retrieval.", + }, + ) @service_api_ns.doc("dataset_hit_testing") @service_api_ns.doc(description="Perform hit testing on a dataset") @service_api_ns.doc(params={"dataset_id": "Dataset ID"}) diff --git a/api/controllers/service_api/dataset/metadata.py b/api/controllers/service_api/dataset/metadata.py index 0a7e3dd00d4..82f571ab0f4 100644 --- a/api/controllers/service_api/dataset/metadata.py +++ b/api/controllers/service_api/dataset/metadata.py @@ -49,6 +49,17 @@ register_response_schema_models( @service_api_ns.route("/datasets//metadata") class DatasetMetadataCreateServiceApi(DatasetApiResource): + @service_api_ns.doc( + summary="Create Metadata Field", + description=( + "Create a custom metadata field for the knowledge base. Metadata fields can be used to " + "annotate documents with structured information." + ), + tags=["Metadata"], + responses={ + 201: "Metadata field created successfully.", + }, + ) @service_api_ns.expect(service_api_ns.models[MetadataArgs.__name__]) @service_api_ns.doc("create_dataset_metadata") @service_api_ns.doc(description="Create metadata for a dataset") @@ -77,6 +88,17 @@ class DatasetMetadataCreateServiceApi(DatasetApiResource): metadata = MetadataService.create_metadata(dataset_id_str, metadata_args) return dump_response(DatasetMetadataResponse, metadata), 201 + @service_api_ns.doc( + summary="List Metadata Fields", + description=( + "Returns the list of all metadata fields (both custom and built-in) for the knowledge base, " + "along with the count of documents using each field." + ), + tags=["Metadata"], + responses={ + 200: "Metadata fields for the knowledge base.", + }, + ) @service_api_ns.doc("get_dataset_metadata") @service_api_ns.doc(description="Get all metadata for a dataset") @service_api_ns.doc(params={"dataset_id": "Dataset ID"}) @@ -102,6 +124,14 @@ class DatasetMetadataCreateServiceApi(DatasetApiResource): @service_api_ns.route("/datasets//metadata/") class DatasetMetadataServiceApi(DatasetApiResource): + @service_api_ns.doc( + summary="Update Metadata Field", + description="Rename a custom metadata field.", + tags=["Metadata"], + responses={ + 200: "Metadata field updated successfully.", + }, + ) @service_api_ns.expect(service_api_ns.models[MetadataUpdatePayload.__name__]) @service_api_ns.doc("update_dataset_metadata") @service_api_ns.doc(description="Update metadata name") @@ -131,6 +161,17 @@ class DatasetMetadataServiceApi(DatasetApiResource): metadata = MetadataService.update_metadata_name(dataset_id_str, metadata_id_str, payload.name) return dump_response(DatasetMetadataResponse, metadata), 200 + @service_api_ns.doc( + summary="Delete Metadata Field", + description=( + "Permanently delete a custom metadata field. Documents using this field will lose their " + "metadata values for it." + ), + tags=["Metadata"], + responses={ + 204: "Success.", + }, + ) @service_api_ns.doc("delete_dataset_metadata") @service_api_ns.doc(description="Delete metadata") @service_api_ns.doc(params={"dataset_id": "Dataset ID", "metadata_id": "Metadata ID"}) @@ -158,6 +199,16 @@ class DatasetMetadataServiceApi(DatasetApiResource): @service_api_ns.route("/datasets//metadata/built-in") class DatasetMetadataBuiltInFieldServiceApi(DatasetApiResource): + @service_api_ns.doc( + summary="Get Built-in Metadata Fields", + description=( + "Returns the list of built-in metadata fields provided by the system (e.g., document type, source URL)." + ), + tags=["Metadata"], + responses={ + 200: "Built-in metadata fields.", + }, + ) @service_api_ns.doc("get_built_in_fields") @service_api_ns.doc(description="Get all built-in metadata fields") @service_api_ns.doc( @@ -179,6 +230,14 @@ class DatasetMetadataBuiltInFieldServiceApi(DatasetApiResource): @service_api_ns.route("/datasets//metadata/built-in/") class DatasetMetadataBuiltInFieldActionServiceApi(DatasetApiResource): + @service_api_ns.doc( + summary="Update Built-in Metadata Field", + description="Enable or disable built-in metadata fields for the knowledge base.", + tags=["Metadata"], + responses={ + 200: "Built-in metadata field toggled successfully.", + }, + ) @service_api_ns.doc("toggle_built_in_field") @service_api_ns.doc(description="Enable or disable built-in metadata field") @service_api_ns.doc(params={"dataset_id": "Dataset ID", "action": BUILT_IN_METADATA_ACTION_PARAM}) @@ -211,6 +270,17 @@ class DatasetMetadataBuiltInFieldActionServiceApi(DatasetApiResource): @service_api_ns.route("/datasets//documents/metadata") class DocumentMetadataEditServiceApi(DatasetApiResource): + @service_api_ns.doc( + summary="Update Document Metadata in Batch", + description=( + "Update metadata values for multiple documents at once. Each document in the request " + "receives the specified metadata key-value pairs." + ), + tags=["Metadata"], + responses={ + 200: "Document metadata updated successfully.", + }, + ) @service_api_ns.expect(service_api_ns.models[MetadataOperationData.__name__]) @service_api_ns.doc("update_documents_metadata") @service_api_ns.doc(description="Update metadata for multiple documents") diff --git a/api/controllers/service_api/dataset/rag_pipeline/rag_pipeline_workflow.py b/api/controllers/service_api/dataset/rag_pipeline/rag_pipeline_workflow.py index a98455062c8..57b360370f4 100644 --- a/api/controllers/service_api/dataset/rag_pipeline/rag_pipeline_workflow.py +++ b/api/controllers/service_api/dataset/rag_pipeline/rag_pipeline_workflow.py @@ -100,6 +100,18 @@ register_response_schema_models( class DatasourcePluginsApi(DatasetApiResource): """Resource for datasource plugins.""" + @service_api_ns.doc( + summary="List Datasource Plugins", + description=( + "List the datasource nodes configured in the knowledge pipeline. Each node includes the " + "plugin it uses plus the metadata needed to run it." + ), + tags=["Knowledge Pipeline"], + responses={ + 200: "List of datasource nodes configured in the pipeline.", + 404: "`not_found` : Dataset not found.", + }, + ) @service_api_ns.doc(shortcut="list_rag_pipeline_datasource_plugins") @service_api_ns.doc(description="List all datasource plugins for a rag pipeline") @service_api_ns.doc( @@ -142,6 +154,18 @@ class DatasourcePluginsApi(DatasetApiResource): class DatasourceNodeRunApi(DatasetApiResource): """Resource for datasource node run.""" + @service_api_ns.doc( + summary="Run Datasource Node", + description=( + "Execute a single datasource node within the knowledge pipeline. Returns a streaming " + "response with the node execution results." + ), + tags=["Knowledge Pipeline"], + responses={ + 200: "Streaming response with node execution events.", + 404: "`not_found` : Dataset not found.", + }, + ) @event_stream_response(service_api_ns) @service_api_ns.doc(shortcut="pipeline_datasource_node_run") @service_api_ns.doc(description="Run a datasource node for a rag pipeline") @@ -201,6 +225,23 @@ class DatasourceNodeRunApi(DatasetApiResource): class PipelineRunApi(DatasetApiResource): """Resource for datasource node run.""" + @service_api_ns.doc( + summary="Run Pipeline", + description=( + "Execute the full knowledge pipeline for a knowledge base. Supports both streaming and " + "blocking response modes." + ), + tags=["Knowledge Pipeline"], + responses={ + 200: ( + "Pipeline execution result. Format depends on `response_mode`: streaming returns a " + "`text/event-stream`, blocking returns a JSON object." + ), + 403: "`forbidden` : Forbidden.", + 404: "`not_found` : Dataset not found.", + 500: "`pipeline_run_error` : Pipeline execution failed.", + }, + ) @json_or_event_stream_response(service_api_ns) @service_api_ns.doc(shortcut="pipeline_datasource_node_run") @service_api_ns.doc(description="Run a datasource node for a rag pipeline") @@ -255,6 +296,21 @@ class PipelineRunApi(DatasetApiResource): class KnowledgebasePipelineFileUploadApi(DatasetApiResource): """Resource for uploading a file to a knowledgebase pipeline.""" + @service_api_ns.doc( + summary="Upload Pipeline File", + description="Upload a file for use in a knowledge pipeline. Accepts a single file via `multipart/form-data`.", + tags=["Knowledge Pipeline"], + responses={ + 201: "File uploaded successfully.", + 400: ( + "- `no_file_uploaded` : Please upload your file.\n" + "- `filename_not_exists_error` : The specified filename does not exist.\n" + "- `too_many_files` : Only one file is allowed." + ), + 413: "`file_too_large` : File size exceeded.", + 415: "`unsupported_file_type` : File type not allowed.", + }, + ) @service_api_ns.doc(shortcut="knowledgebase_pipeline_file_upload") @service_api_ns.doc(description="Upload a file to a knowledgebase pipeline") @service_api_ns.doc(consumes=["multipart/form-data"], params=multipart_file_params(include_user=False)) diff --git a/api/controllers/service_api/dataset/segment.py b/api/controllers/service_api/dataset/segment.py index f93eb6a4bf1..c334649c602 100644 --- a/api/controllers/service_api/dataset/segment.py +++ b/api/controllers/service_api/dataset/segment.py @@ -128,6 +128,18 @@ register_response_schema_models( class SegmentApi(DatasetApiResource): """Resource for segments.""" + @service_api_ns.doc( + summary="Create Chunks", + description=( + "Create one or more chunks within a document. Each chunk can include optional keywords and an " + "answer field (for QA-mode documents)." + ), + tags=["Chunks"], + responses={ + 200: "Chunks created successfully.", + 404: "`not_found` : Document is not completed or is disabled.", + }, + ) @service_api_ns.expect(service_api_ns.models[SegmentCreatePayload.__name__]) @service_api_ns.doc("create_segments") @service_api_ns.doc(description="Create segments in a document") @@ -209,6 +221,14 @@ class SegmentApi(DatasetApiResource): } return dump_response(SegmentCreateListResponse, response), 200 + @service_api_ns.doc( + summary="List Chunks", + description="Returns a paginated list of chunks within a document. Supports filtering by keyword and status.", + tags=["Chunks"], + responses={ + 200: "List of chunks.", + }, + ) @service_api_ns.doc("list_segments") @service_api_ns.doc(description="List segments in a document") @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT) @@ -294,6 +314,14 @@ class SegmentApi(DatasetApiResource): @service_api_ns.route("/datasets//documents//segments/") class DatasetSegmentApi(DatasetApiResource): + @service_api_ns.doc( + summary="Delete Chunk", + description="Permanently delete a chunk from the document.", + tags=["Chunks"], + responses={ + 204: "Success.", + }, + ) @service_api_ns.doc("delete_segment") @service_api_ns.doc(description="Delete a specific segment") @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT) @@ -329,6 +357,14 @@ class DatasetSegmentApi(DatasetApiResource): SegmentService.delete_segment(segment, document, dataset) return "", 204 + @service_api_ns.doc( + summary="Update Chunk", + description="Update a chunk's content, keywords, or answer. Re-triggers indexing for the modified chunk.", + tags=["Chunks"], + responses={ + 200: "Chunk updated successfully.", + }, + ) @service_api_ns.expect(service_api_ns.models[SegmentUpdatePayload.__name__]) @service_api_ns.doc("update_segment") @service_api_ns.doc(description="Update a specific segment") @@ -391,6 +427,17 @@ class DatasetSegmentApi(DatasetApiResource): } return dump_response(SegmentDetailResponse, response), 200 + @service_api_ns.doc( + summary="Get Chunk", + description=( + "Retrieve detailed information about a specific chunk, including its content, keywords, and " + "indexing status." + ), + tags=["Chunks"], + responses={ + 200: "Chunk details.", + }, + ) @service_api_ns.doc("get_segment") @service_api_ns.doc(description="Get a specific segment by ID") @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT) @@ -442,6 +489,15 @@ class DatasetSegmentApi(DatasetApiResource): class ChildChunkApi(DatasetApiResource): """Resource for child chunks.""" + @service_api_ns.doc( + summary="Create Child Chunk", + description="Create a child chunk under the specified segment.", + tags=["Chunks"], + responses={ + 200: "Child chunk created successfully.", + 400: "`invalid_param` : Create child chunk index failed.", + }, + ) @service_api_ns.expect(service_api_ns.models[ChildChunkCreatePayload.__name__]) @service_api_ns.doc("create_child_chunk") @service_api_ns.doc(description="Create a new child chunk for a segment") @@ -511,6 +567,14 @@ class ChildChunkApi(DatasetApiResource): return dump_response(ChildChunkDetailResponse, {"data": child_chunk}), 200 + @service_api_ns.doc( + summary="List Child Chunks", + description="Returns a paginated list of child chunks under a specific parent chunk.", + tags=["Chunks"], + responses={ + 200: "List of child chunks.", + }, + ) @service_api_ns.doc("list_child_chunks") @service_api_ns.doc(description="List child chunks for a segment") @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_PARENT_SEGMENT) @@ -576,6 +640,15 @@ class ChildChunkApi(DatasetApiResource): class DatasetChildChunkApi(DatasetApiResource): """Resource for updating child chunks.""" + @service_api_ns.doc( + summary="Delete Child Chunk", + description="Permanently delete a child chunk from its parent chunk.", + tags=["Chunks"], + responses={ + 204: "Success.", + 400: "`invalid_param` : Delete child chunk index failed.", + }, + ) @service_api_ns.doc("delete_child_chunk") @service_api_ns.doc(description="Delete a specific child chunk") @service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_CHILD_CHUNK) @@ -634,6 +707,15 @@ class DatasetChildChunkApi(DatasetApiResource): return "", 204 + @service_api_ns.doc( + summary="Update Child Chunk", + description="Update the content of an existing child chunk.", + tags=["Chunks"], + responses={ + 200: "Child chunk updated successfully.", + 400: "`invalid_param` : Update child chunk index failed.", + }, + ) @service_api_ns.expect(service_api_ns.models[ChildChunkUpdatePayload.__name__]) @service_api_ns.doc("update_child_chunk") @service_api_ns.doc(description="Update a specific child chunk") diff --git a/api/controllers/service_api/end_user/end_user.py b/api/controllers/service_api/end_user/end_user.py index d2d018492a5..607ed12e5b6 100644 --- a/api/controllers/service_api/end_user/end_user.py +++ b/api/controllers/service_api/end_user/end_user.py @@ -17,6 +17,18 @@ register_response_schema_models(service_api_ns, EndUserDetail) class EndUserApi(Resource): """Resource for retrieving end user details by ID.""" + @service_api_ns.doc( + summary="Get End User Info", + description=( + "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., " + "`created_by` from [Upload File](/api-reference/files/upload-file))." + ), + tags=["End Users"], + responses={ + 200: "End user retrieved successfully.", + 404: "`end_user_not_found` : End user not found.", + }, + ) @service_api_ns.doc("get_end_user") @service_api_ns.doc(description="Get an end user by ID") @service_api_ns.doc( diff --git a/api/controllers/service_api/workspace/models.py b/api/controllers/service_api/workspace/models.py index 63806ab252f..9d49866e87a 100644 --- a/api/controllers/service_api/workspace/models.py +++ b/api/controllers/service_api/workspace/models.py @@ -19,6 +19,17 @@ register_response_schema_models(service_api_ns, ProviderWithModelsListResponse) @service_api_ns.route("/workspaces/current/models/model-types/") class ModelProviderAvailableModelApi(Resource): + @service_api_ns.doc( + summary="Get Available Models", + description=( + "Retrieve the list of available models by type. Primarily used to query `text-embedding` and " + "`rerank` models for knowledge base configuration." + ), + tags=["Models"], + responses={ + 200: "Available models for the specified type.", + }, + ) @service_api_ns.doc("get_available_models") @service_api_ns.doc(description="Get available models by model type") @service_api_ns.doc(params={"model_type": "Type of model to retrieve"}) diff --git a/api/libs/flask_restx_compat.py b/api/libs/flask_restx_compat.py index fb30cbbc60c..a442be01d84 100644 --- a/api/libs/flask_restx_compat.py +++ b/api/libs/flask_restx_compat.py @@ -15,6 +15,7 @@ from flask_restx import fields from flask_restx import swagger as restx_swagger from flask_restx.model import Model, OrderedModel, instance from flask_restx.swagger import Swagger +from flask_restx.utils import not_none def _is_inline_field_map(value: object) -> TypeGuard[dict[object, object]]: @@ -118,6 +119,9 @@ def install_swagger_compatibility() -> None: original_register_field = Swagger.register_field original_extract_path_params = restx_swagger.extract_path_params original_schema_from_parameter = Swagger.schema_from_parameter + original_description_for = Swagger.description_for + original_serialize_operation = Swagger.serialize_operation + original_parameters_and_request_body_for = Swagger.parameters_and_request_body_for original_as_dict = Swagger.as_dict def get_or_create_inline_model(self: Swagger, nested_fields: dict[object, object]) -> object: @@ -154,6 +158,51 @@ def install_swagger_compatibility() -> None: params[variable]["format"] = "uuid" return params + def description_for_with_explicit_summary(self: Swagger, doc: dict[str, object], method: str): + method_doc = doc.get(method) + if ( + isinstance(method_doc, dict) + and isinstance(method_doc.get("summary"), str) + and isinstance(method_doc.get("description"), str) + ): + return method_doc["description"] + return original_description_for(self, doc, method) + + def serialize_operation_with_explicit_summary_tags( + self: Swagger, doc: dict[str, object], method: str, inherited_request_body=None + ): + operation = original_serialize_operation(self, doc, method, inherited_request_body) + method_doc = doc.get(method) + if not isinstance(method_doc, dict): + return operation + + summary = method_doc.get("summary") + if isinstance(summary, str): + operation["summary"] = summary + + tags = method_doc.get("tags") + if isinstance(tags, list) and all(isinstance(tag, str) for tag in tags): + operation["tags"] = tags + + return operation + + def serialize_resource_with_explicit_operation_tags(self: Swagger, ns, resource, url, route_doc=None, **kwargs): + doc = self.extract_resource_doc(resource, url, route_doc=route_doc) + if doc is False: + return None + + path_params, path_request_body = original_parameters_and_request_body_for(self, doc) + path: dict[str, object] = {"parameters": path_params or None} + methods = [method.lower() for method in resource.methods or []] + requested_methods = [method.lower() for method in kwargs.get("methods", [])] + for method in methods: + if doc[method] is False or requested_methods and method not in requested_methods: + continue + operation = self.serialize_operation(doc, method, path_request_body) + operation.setdefault("tags", [ns.name]) + path[method] = operation + return not_none(path) + def as_dict_with_inline_dict_support(self: Swagger): # Temporary set RESTX_INCLUDE_ALL_MODELS = false to prevent "length changed while iterating" error include_all_models = current_app.config.get("RESTX_INCLUDE_ALL_MODELS", False) @@ -167,5 +216,8 @@ def install_swagger_compatibility() -> None: Swagger.register_field = register_field_with_inline_dict_support restx_swagger.extract_path_params = extract_path_params_with_uuid_format Swagger.schema_from_parameter = schema_from_parameter_with_description + Swagger.description_for = description_for_with_explicit_summary + Swagger.serialize_operation = serialize_operation_with_explicit_summary_tags + Swagger.serialize_resource = serialize_resource_with_explicit_operation_tags Swagger.as_dict = as_dict_with_inline_dict_support Swagger._dify_swagger_compatibility_installed = True diff --git a/api/openapi/markdown/console-openapi.md b/api/openapi/markdown/console-openapi.md index a559a526e75..fd278d42372 100644 --- a/api/openapi/markdown/console-openapi.md +++ b/api/openapi/markdown/console-openapi.md @@ -18690,7 +18690,7 @@ Tag type | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | message_id | string | Message ID | No | -| streaming | boolean | Enable streaming response | No | +| streaming | boolean | Reserved for compatibility; TTS response streaming is determined by the provider output. | No | | text | string | Text to convert to audio | No | | voice | string | Voice to use for TTS | No | diff --git a/api/openapi/markdown/service-openapi.md b/api/openapi/markdown/service-openapi.md index b05cf1c87d3..fdce4d1a2c2 100644 --- a/api/openapi/markdown/service-openapi.md +++ b/api/openapi/markdown/service-openapi.md @@ -19,706 +19,6 @@ Service operations | ---- | ----------- | ------ | | 200 | Success | **application/json**: [IndexInfoResponse](#indexinforesponse)
| -### [GET] /app/feedbacks -**Get all feedbacks for the application** - -Get all feedbacks for the application -Returns paginated list of all feedback submitted for messages in this app. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| limit | query | Number of feedbacks per page | No | integer,
**Default:** 20 | -| page | query | Page number | No | integer,
**Default:** 1 | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Feedbacks retrieved successfully | **application/json**: [AppFeedbackListResponse](#appfeedbacklistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | - -### [POST] /apps/annotation-reply/{action} -**Enable or disable annotation reply feature** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| action | path | Action to perform: 'enable' or 'disable' | Yes | string,
**Available values:** "disable", "enable" | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [AnnotationReplyActionPayload](#annotationreplyactionpayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Action completed successfully | **application/json**: [AnnotationJobStatusResponse](#annotationjobstatusresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | - -### [GET] /apps/annotation-reply/{action}/status/{job_id} -**Get the status of an annotation reply action job** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| action | path | Action type | Yes | string | -| job_id | path | Job ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Job status retrieved successfully | **application/json**: [AnnotationJobStatusResponse](#annotationjobstatusresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Job not found | | - -### [GET] /apps/annotations -**List annotations for the application** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| keyword | query | Keyword to search annotations | No | string | -| limit | query | Number of annotations per page | No | integer,
**Default:** 20 | -| page | query | Page number | No | integer,
**Default:** 1 | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Annotations retrieved successfully | **application/json**: [AnnotationList](#annotationlist)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | - -### [POST] /apps/annotations -**Create a new annotation** - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [AnnotationCreatePayload](#annotationcreatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 201 | Annotation created successfully | **application/json**: [Annotation](#annotation)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | - -### [DELETE] /apps/annotations/{annotation_id} -**Delete an annotation** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| annotation_id | path | Annotation ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 204 | Annotation deleted successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - insufficient permissions | -| 404 | Annotation not found | - -### [PUT] /apps/annotations/{annotation_id} -**Update an existing annotation** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| annotation_id | path | Annotation ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [AnnotationCreatePayload](#annotationcreatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Annotation updated successfully | **application/json**: [Annotation](#annotation)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - insufficient permissions | | -| 404 | Annotation not found | | - -### [POST] /audio-to-text -**Convert audio to text using speech-to-text** - -Convert audio to text using speech-to-text -Accepts an audio file upload and returns the transcribed text. - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **multipart/form-data**: { **"file"**: binary, **"user"**: string }
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Audio successfully transcribed | **application/json**: [AudioTranscriptResponse](#audiotranscriptresponse)
| -| 400 | Bad request - no audio or invalid audio | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 413 | Audio file too large | | -| 415 | Unsupported audio type | | -| 500 | Internal server error | | - -### [POST] /chat-messages -**Send a message in a chat conversation** - -Send a message in a chat conversation -This endpoint handles chat messages for chat, agent chat, and advanced chat applications. -Supports conversation management and both blocking and streaming response modes. - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [ChatRequestPayloadWithUser](#chatrequestpayloadwithuser)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Message sent successfully | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| -| 400 | Bad request - invalid parameters or workflow issues | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Conversation or workflow not found | | -| 429 | Rate limit exceeded | | -| 500 | Internal server error | | - -### [POST] /chat-messages/{task_id}/stop -**Stop a running chat message generation** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| task_id | path | The ID of the task to stop | Yes | string | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [RequiredServiceApiUserPayload](#requiredserviceapiuserpayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Task stopped successfully | **application/json**: [SimpleResultResponse](#simpleresultresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Task not found | | - -### [POST] /completion-messages -**Create a completion for the given prompt** - -Create a completion for the given prompt -This endpoint generates a completion based on the provided inputs and query. -Supports both blocking and streaming response modes. - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [CompletionRequestPayloadWithUser](#completionrequestpayloadwithuser)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Completion created successfully | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| -| 400 | Bad request - invalid parameters | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Conversation not found | | -| 500 | Internal server error | | - -### [POST] /completion-messages/{task_id}/stop -**Stop a running completion task** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| task_id | path | The ID of the task to stop | Yes | string | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [RequiredServiceApiUserPayload](#requiredserviceapiuserpayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Task stopped successfully | **application/json**: [SimpleResultResponse](#simpleresultresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Task not found | | - -### [GET] /conversations -**List all conversations for the current user** - -List all conversations for the current user -Supports pagination using last_id and limit parameters. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| last_id | query | Last conversation ID for pagination | No | string | -| limit | query | Number of conversations to return | No | integer,
**Default:** 20 | -| sort_by | query | Sort order for conversations | No | string,
**Available values:** "-created_at", "-updated_at", "created_at", "updated_at",
**Default:** -updated_at | -| user | query | End user identifier | No | string | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Conversations retrieved successfully | **application/json**: [ConversationInfiniteScrollPagination](#conversationinfinitescrollpagination)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Last conversation not found | | - -### [DELETE] /conversations/{c_id} -**Delete a specific conversation** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| c_id | path | Conversation ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [OptionalServiceApiUserPayload](#optionalserviceapiuserpayload)
| - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 204 | Conversation deleted successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | -| 404 | Conversation not found | - -### [POST] /conversations/{c_id}/name -**Rename a conversation or auto-generate a name** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| c_id | path | Conversation ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [ConversationRenamePayloadWithUser](#conversationrenamepayloadwithuser)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Conversation renamed successfully | **application/json**: [SimpleConversation](#simpleconversation)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Conversation not found | | - -### [GET] /conversations/{c_id}/variables -**List all variables for a conversation** - -List all variables for a conversation -Conversational variables are only available for chat applications. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| c_id | path | Conversation ID | Yes | string (uuid) | -| last_id | query | Last variable ID for pagination | No | string | -| limit | query | Number of variables to return | No | integer,
**Default:** 20 | -| user | query | End user identifier | No | string | -| variable_name | query | Filter variables by name | No | string | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Variables retrieved successfully | **application/json**: [ConversationVariableInfiniteScrollPaginationResponse](#conversationvariableinfinitescrollpaginationresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Conversation not found | | - -### [PUT] /conversations/{c_id}/variables/{variable_id} -**Update a conversation variable's value** - -Update a conversation variable's value -Allows updating the value of a specific conversation variable. -The value must match the variable's expected type. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| c_id | path | Conversation ID | Yes | string (uuid) | -| variable_id | path | Variable ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [ConversationVariableUpdatePayloadWithUser](#conversationvariableupdatepayloadwithuser)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Variable updated successfully | **application/json**: [ConversationVariableResponse](#conversationvariableresponse)
| -| 400 | Bad request - type mismatch | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Conversation or variable not found | | - -### [GET] /datasets -**Resource for getting datasets** - -List all datasets - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| include_all | query | Include all datasets | No | boolean | -| keyword | query | Search keyword | No | string | -| limit | query | Number of items per page | No | integer,
**Default:** 20 | -| page | query | Page number | No | integer,
**Default:** 1 | -| tag_ids | query | Filter by tag IDs | No | [ string ] | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Datasets retrieved successfully | **application/json**: [DatasetListResponse](#datasetlistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### [POST] /datasets -**Resource for creating datasets** - -Create a new dataset - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [DatasetCreatePayload](#datasetcreatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Dataset created successfully | **application/json**: [DatasetDetailResponse](#datasetdetailresponse)
| -| 400 | Bad request - invalid parameters | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### [POST] /datasets/pipeline/file-upload -**Upload a file for use in conversations** - -Upload a file to a knowledgebase pipeline -Accepts a single file upload via multipart/form-data. - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **multipart/form-data**: { **"file"**: binary }
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 201 | File uploaded successfully | **application/json**: [PipelineUploadFileResponse](#pipelineuploadfileresponse)
| -| 400 | Bad request - no file or invalid file | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 413 | File too large | | -| 415 | Unsupported file type | | - -### [DELETE] /datasets/tags -**Delete a knowledge type tag** - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [TagDeletePayload](#tagdeletepayload)
| - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 204 | Tag deleted successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - insufficient permissions | - -### [GET] /datasets/tags -**Get all knowledge type tags** - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Tags retrieved successfully | **application/json**: [KnowledgeTagListResponse](#knowledgetaglistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### [PATCH] /datasets/tags -Update a knowledge type tag - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [TagUpdatePayload](#tagupdatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Tag updated successfully | **application/json**: [KnowledgeTagResponse](#knowledgetagresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - insufficient permissions | | - -### [POST] /datasets/tags -**Add a knowledge type tag** - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [TagCreatePayload](#tagcreatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Tag created successfully | **application/json**: [KnowledgeTagResponse](#knowledgetagresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - insufficient permissions | | - -### [POST] /datasets/tags/binding -Bind tags to a dataset - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [TagBindingPayload](#tagbindingpayload)
| - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 204 | Tags bound successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - insufficient permissions | - -### [POST] /datasets/tags/unbinding -Unbind tags from a dataset - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [TagUnbindingPayload](#tagunbindingpayload)
| - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 204 | Tags unbound successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - insufficient permissions | - -### [DELETE] /datasets/{dataset_id} -**Deletes a dataset given its ID** - -Delete a dataset -Args: - _: ignore - dataset_id (UUID): The ID of the dataset to be deleted. - -Returns: - dict: A dictionary with a key 'result' and a value 'success' - if the dataset was successfully deleted. Omitted in HTTP response. - int: HTTP status code 204 indicating that the operation was successful. - -Raises: - NotFound: If the dataset with the given ID does not exist. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 204 | Dataset deleted successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - dataset API access or workspace access denied | -| 404 | Dataset not found | -| 409 | Conflict - dataset is in use | - -### [GET] /datasets/{dataset_id} -Get a specific dataset by ID - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Dataset retrieved successfully | **application/json**: [DatasetDetailWithPartialMembersResponse](#datasetdetailwithpartialmembersresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - insufficient permissions | | -| 404 | Dataset not found | | - -### [PATCH] /datasets/{dataset_id} -Update an existing dataset - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [DatasetUpdatePayload](#datasetupdatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Dataset updated successfully | **application/json**: [DatasetDetailWithPartialMembersResponse](#datasetdetailwithpartialmembersresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - insufficient permissions | | -| 404 | Dataset not found | | - -### [POST] /datasets/{dataset_id}/document/create-by-file -Create a new document by uploading a file - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **multipart/form-data**: { **"data"**: string, **"file"**: binary }
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Document created successfully | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| -| 400 | Bad request - invalid file or parameters | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### [POST] /datasets/{dataset_id}/document/create-by-text -Create a new document by providing text content - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [DocumentTextCreatePayload](#documenttextcreatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Document created successfully | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| -| 400 | Bad request - invalid parameters | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### ~~[POST] /datasets/{dataset_id}/document/create_by_file~~ - -***DEPRECATED*** - -Create a new document by uploading a file - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **multipart/form-data**: { **"data"**: string, **"file"**: binary }
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Document created successfully | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| -| 400 | Bad request - invalid file or parameters | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - ### ~~[POST] /datasets/{dataset_id}/document/create_by_text~~ ***DEPRECATED*** @@ -746,140 +46,10 @@ Deprecated legacy alias for creating a new document by providing text content. U | 401 | Unauthorized - invalid API token | | | 403 | Forbidden - dataset API access or workspace access denied | | -### [GET] /datasets/{dataset_id}/documents -List all documents in a dataset - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| keyword | query | Search keyword | No | string | -| limit | query | Number of items per page | No | integer,
**Default:** 20 | -| page | query | Page number | No | integer,
**Default:** 1 | -| status | query | Document status filter | No | string | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Documents retrieved successfully | **application/json**: [DocumentListResponse](#documentlistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset not found | | - -### [POST] /datasets/{dataset_id}/documents/download-zip -Download selected uploaded documents as a single ZIP archive - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [DocumentBatchDownloadZipPayload](#documentbatchdownloadzippayload)
| - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 200 | ZIP archive generated successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - insufficient permissions | -| 404 | Document or dataset not found | - -### [POST] /datasets/{dataset_id}/documents/metadata -**Update metadata for multiple documents** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [MetadataOperationData](#metadataoperationdata)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Documents metadata updated successfully | **application/json**: [DatasetMetadataActionResponse](#datasetmetadataactionresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset not found | | - -### [PATCH] /datasets/{dataset_id}/documents/status/{action} -**Batch update document status** - -Batch update document status -Args: - tenant_id: tenant id - dataset_id: dataset id - action: action to perform (Literal["enable", "disable", "archive", "un_archive"]) - -Returns: - dict: A dictionary with a key 'result' and a value 'success' - int: HTTP status code 200 indicating that the operation was successful. - -Raises: - NotFound: If the dataset with the given ID does not exist. - Forbidden: If the user does not have permission. - InvalidActionError: If the action is invalid or cannot be performed. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| action | path | Action to perform: 'enable', 'disable', 'archive', or 'un_archive' | Yes | string,
**Available values:** "archive", "disable", "enable", "un_archive" | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [DocumentStatusPayload](#documentstatuspayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Document status updated successfully | **application/json**: [SimpleResultResponse](#simpleresultresponse)
| -| 400 | Bad request - invalid action | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - insufficient permissions | | -| 404 | Dataset not found | | - -### [GET] /datasets/{dataset_id}/documents/{batch}/indexing-status -Get indexing status for documents in a batch - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| batch | path | Batch ID | Yes | string | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Indexing status retrieved successfully | **application/json**: [DocumentStatusListResponse](#documentstatuslistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset or documents not found | | - ### [DELETE] /datasets/{dataset_id}/documents/{document_id} -**Delete document** +**Delete Document** -Delete a document +Permanently delete a document and all its chunks from the knowledge base. #### Parameters @@ -892,13 +62,16 @@ Delete a document | Code | Description | | ---- | ----------- | -| 204 | Document deleted successfully | +| 204 | Success. | +| 400 | `document_indexing` : Cannot delete document during indexing. | | 401 | Unauthorized - invalid API token | -| 403 | Forbidden - document is archived | -| 404 | Document not found | +| 403 | `archived_document_immutable` : The archived document is not editable. | +| 404 | `not_found` : Document Not Exists. | ### [GET] /datasets/{dataset_id}/documents/{document_id} -Get a specific document by ID +**Get Document** + +Retrieve detailed information about a specific document, including its indexing status, metadata, and processing statistics. #### Parameters @@ -912,10 +85,11 @@ Get a specific document by ID | Code | Description | Schema | | ---- | ----------- | ------ | -| 200 | Document retrieved successfully | **application/json**: [DocumentDetailResponse](#documentdetailresponse)
| +| 200 | Document details. The response shape varies based on the `metadata` query parameter. When `metadata` is `only`, only `id`, `doc_type`, and `doc_metadata` are returned. When `metadata` is `without`, `doc_type` and `doc_metadata` are omitted. | **application/json**: [DocumentDetailResponse](#documentdetailresponse)
| +| 400 | `invalid_metadata` : Invalid metadata value for the specified key. | | | 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - insufficient permissions | | -| 404 | Document not found | | +| 403 | `forbidden` : No permission. | | +| 404 | `not_found` : Document not found. | | ### [PATCH] /datasets/{dataset_id}/documents/{document_id} Update an existing document by uploading a file @@ -942,318 +116,6 @@ Update an existing document by uploading a file | 403 | Forbidden - dataset API access or workspace access denied | | | 404 | Document not found | | -### [GET] /datasets/{dataset_id}/documents/{document_id}/download -Get a signed download URL for a document's original uploaded file - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Download URL generated successfully | **application/json**: [UrlResponse](#urlresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - insufficient permissions | | -| 404 | Document or upload file not found | | - -### [GET] /datasets/{dataset_id}/documents/{document_id}/segments -List segments in a document - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | -| keyword | query | | No | string | -| limit | query | | No | integer,
**Default:** 20 | -| page | query | | No | integer,
**Default:** 1 | -| status | query | | No | [ string ] | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Segments retrieved successfully | **application/json**: [SegmentListResponse](#segmentlistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset or document not found | | - -### [POST] /datasets/{dataset_id}/documents/{document_id}/segments -Create segments in a document - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [SegmentCreatePayload](#segmentcreatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Segments created successfully | **application/json**: [SegmentCreateListResponse](#segmentcreatelistresponse)
| -| 400 | Bad request - segments data is missing | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset or document not found | | - -### [DELETE] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id} -Delete a specific segment - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | -| segment_id | path | Segment ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 204 | Segment deleted successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - dataset API access or workspace access denied | -| 404 | Dataset, document, or segment not found | - -### [GET] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id} -Get a specific segment by ID - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | -| segment_id | path | Segment ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Segment retrieved successfully | **application/json**: [SegmentDetailResponse](#segmentdetailresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset, document, or segment not found | | - -### [POST] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id} -Update a specific segment - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | -| segment_id | path | Segment ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [SegmentUpdatePayload](#segmentupdatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Segment updated successfully | **application/json**: [SegmentDetailResponse](#segmentdetailresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset, document, or segment not found | | - -### [GET] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks -List child chunks for a segment - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | -| segment_id | path | Parent segment ID | Yes | string (uuid) | -| keyword | query | | No | string | -| limit | query | | No | integer,
**Default:** 20 | -| page | query | | No | integer,
**Default:** 1 | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Child chunks retrieved successfully | **application/json**: [ChildChunkListResponse](#childchunklistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset, document, or segment not found | | - -### [POST] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks -Create a new child chunk for a segment - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | -| segment_id | path | Parent segment ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [ChildChunkCreatePayload](#childchunkcreatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Child chunk created successfully | **application/json**: [ChildChunkDetailResponse](#childchunkdetailresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset, document, or segment not found | | - -### [DELETE] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id} -Delete a specific child chunk - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| child_chunk_id | path | Child chunk ID | Yes | string (uuid) | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | -| segment_id | path | Parent segment ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 204 | Child chunk deleted successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - dataset API access or workspace access denied | -| 404 | Dataset, document, segment, or child chunk not found | - -### [PATCH] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id} -Update a specific child chunk - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| child_chunk_id | path | Child chunk ID | Yes | string (uuid) | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | -| segment_id | path | Parent segment ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [ChildChunkUpdatePayload](#childchunkupdatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Child chunk updated successfully | **application/json**: [ChildChunkDetailResponse](#childchunkdetailresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset, document, segment, or child chunk not found | | - -### ~~[POST] /datasets/{dataset_id}/documents/{document_id}/update-by-file~~ - -***DEPRECATED*** - -Deprecated legacy alias for updating an existing document by uploading a file. Use PATCH /datasets/{dataset_id}/documents/{document_id} instead. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| No | **multipart/form-data**: { **"data"**: string, **"file"**: binary }
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Document updated successfully | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Document not found | | - -### [POST] /datasets/{dataset_id}/documents/{document_id}/update-by-text -Update an existing document by providing text content - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [DocumentTextUpdate](#documenttextupdate)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Document updated successfully | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Document not found | | - -### ~~[POST] /datasets/{dataset_id}/documents/{document_id}/update_by_file~~ - -***DEPRECATED*** - -Deprecated legacy alias for updating an existing document by uploading a file. Use PATCH /datasets/{dataset_id}/documents/{document_id} instead. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| document_id | path | Document ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| No | **multipart/form-data**: { **"data"**: string, **"file"**: binary }
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Document updated successfully | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Document not found | | - ### ~~[POST] /datasets/{dataset_id}/documents/{document_id}/update_by_text~~ ***DEPRECATED*** @@ -1282,430 +144,33 @@ Deprecated legacy alias for updating an existing document by providing text cont | 403 | Forbidden - dataset API access or workspace access denied | | | 404 | Document not found | | -### [POST] /datasets/{dataset_id}/hit-testing -**Perform hit testing on a dataset** +--- +## default -Perform hit testing on a dataset -Tests retrieval performance for the specified dataset. +### [GET] /app/feedbacks +**List App Feedbacks** + +Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback. #### Parameters | Name | Located in | Description | Required | Schema | | ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [HitTestingPayload](#hittestingpayload)
| +| limit | query | Number of feedbacks per page | No | integer,
**Default:** 20 | +| page | query | Page number | No | integer,
**Default:** 1 | #### Responses | Code | Description | Schema | | ---- | ----------- | ------ | -| 200 | Hit testing results | **application/json**: [HitTestingResponse](#hittestingresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset not found | | - -### [GET] /datasets/{dataset_id}/metadata -**Get all metadata for a dataset** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Metadata retrieved successfully | **application/json**: [DatasetMetadataListResponse](#datasetmetadatalistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset not found | | - -### [POST] /datasets/{dataset_id}/metadata -**Create metadata for a dataset** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [MetadataArgs](#metadataargs)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 201 | Metadata created successfully | **application/json**: [DatasetMetadataResponse](#datasetmetadataresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset not found | | - -### [GET] /datasets/{dataset_id}/metadata/built-in -**Get all built-in metadata fields** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Built-in fields retrieved successfully | **application/json**: [DatasetMetadataBuiltInFieldsResponse](#datasetmetadatabuiltinfieldsresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### [POST] /datasets/{dataset_id}/metadata/built-in/{action} -**Enable or disable built-in metadata field** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| action | path | Action to perform: 'enable' or 'disable' | Yes | string,
**Available values:** "disable", "enable" | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Action completed successfully | **application/json**: [DatasetMetadataActionResponse](#datasetmetadataactionresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset not found | | - -### [DELETE] /datasets/{dataset_id}/metadata/{metadata_id} -**Delete metadata** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| metadata_id | path | Metadata ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 204 | Metadata deleted successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - dataset API access or workspace access denied | -| 404 | Dataset or metadata not found | - -### [PATCH] /datasets/{dataset_id}/metadata/{metadata_id} -**Update metadata name** - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | -| metadata_id | path | Metadata ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [MetadataUpdatePayload](#metadataupdatepayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Metadata updated successfully | **application/json**: [DatasetMetadataResponse](#datasetmetadataresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset or metadata not found | | - -### [GET] /datasets/{dataset_id}/pipeline/datasource-plugins -**Resource for getting datasource plugins** - -List all datasource plugins for a rag pipeline - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| is_published | query | | No | boolean,
**Default:** true | -| dataset_id | path | | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Datasource plugins retrieved successfully | **application/json**: [DatasourcePluginListResponse](#datasourcepluginlistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### [POST] /datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run -**Resource for getting datasource plugins** - -Run a datasource node for a rag pipeline - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | | Yes | string (uuid) | -| node_id | path | | Yes | string | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [DatasourceNodeRunPayload](#datasourcenoderunpayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Datasource node run successfully | **text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### [POST] /datasets/{dataset_id}/pipeline/run -**Resource for running a rag pipeline** - -Run a datasource node for a rag pipeline - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [PipelineRunApiEntity](#pipelinerunapientity)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Pipeline run successfully | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### [POST] /datasets/{dataset_id}/retrieve -**Perform hit testing on a dataset** - -Perform hit testing on a dataset -Tests retrieval performance for the specified dataset. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [HitTestingPayload](#hittestingpayload)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Hit testing results | **application/json**: [HitTestingResponse](#hittestingresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | -| 404 | Dataset not found | | - -### [GET] /datasets/{dataset_id}/tags -**Get all knowledge type tags** - -Get tags bound to a specific dataset - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| dataset_id | path | Dataset ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Tags retrieved successfully | **application/json**: [DatasetBoundTagListResponse](#datasetboundtaglistresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - dataset API access or workspace access denied | | - -### [GET] /end-users/{end_user_id} -**Get end user detail** - -Get an end user by ID -This endpoint is scoped to the current app token's tenant/app to prevent -cross-tenant/app access when an end-user ID is known. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| end_user_id | path | End user ID | Yes | string (uuid) | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | End user retrieved successfully | **application/json**: [EndUserDetail](#enduserdetail)
| +| 200 | A list of application feedbacks. | **application/json**: [AppFeedbackListResponse](#appfeedbacklistresponse)
| | 401 | Unauthorized - invalid API token | | | 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | End user not found | | - -### [POST] /files/upload -**Upload a file for use in conversations** - -Upload a file for use in conversations -Accepts a single file upload via multipart/form-data. - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **multipart/form-data**: { **"file"**: binary, **"user"**: string }
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 201 | File uploaded successfully | **application/json**: [FileResponse](#fileresponse)
| -| 400 | Bad request - no file or invalid file | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 413 | File too large | | -| 415 | Unsupported file type | | - -### [GET] /files/{file_id}/preview -**Preview/Download a file that was uploaded via Service API** - -Preview or download a file uploaded via Service API -Provides secure file preview/download functionality. -Files can only be accessed if they belong to messages within the requesting app's context. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| file_id | path | UUID of the file to preview | Yes | string (uuid) | -| as_attachment | query | Download as attachment | No | boolean | -| user | query | End user identifier | No | string | - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 200 | File retrieved successfully | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - file access denied | -| 404 | File not found | - -### [GET] /form/human_input/{form_token} -Get a paused human input form by token - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| form_token | path | Human input form token | Yes | string | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Form retrieved successfully | **application/json**: [HumanInputFormDefinitionResponse](#humaninputformdefinitionresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Form not found | | -| 412 | Form already submitted or expired | | - -### [POST] /form/human_input/{form_token} -Submit a paused human input form by token - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| form_token | path | Human input form token | Yes | string | - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [HumanInputFormSubmitPayloadWithUser](#humaninputformsubmitpayloadwithuser)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Form submitted successfully | **application/json**: [HumanInputFormSubmitResponse](#humaninputformsubmitresponse)
| -| 400 | Bad request - invalid submission data | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Form not found | | -| 412 | Form already submitted or expired | | - -### [GET] /info -**Get app information** - -Get basic application information -Returns basic information about the application including name, description, tags, and mode. - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Application info retrieved successfully | **application/json**: [AppInfoResponse](#appinforesponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Application not found | | - -### [GET] /messages -**List messages in a conversation** - -List messages in a conversation -Retrieves messages with pagination support using first_id. - -#### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| conversation_id | query | Conversation UUID | Yes | string | -| first_id | query | First message ID for pagination | No | string | -| limit | query | Number of messages to return (1-100) | No | integer,
**Default:** 20 | -| user | query | End user identifier | No | string | - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Messages retrieved successfully | **application/json**: [MessageInfiniteScrollPagination](#messageinfinitescrollpagination)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Conversation or first message not found | | ### [POST] /messages/{message_id}/feedbacks -**Submit feedback for a message** +**Submit Message Feedback** -Submit feedback for a message -Allows users to rate messages as like/dislike and provide optional feedback content. +Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback. #### Parameters @@ -1726,13 +191,248 @@ Allows users to rate messages as like/dislike and provide optional feedback cont | 200 | Feedback submitted successfully | **application/json**: [ResultResponse](#resultresponse)
| | 401 | Unauthorized - invalid API token | | | 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Message not found | | +| 404 | `not_found` : Message does not exist. | | + +--- +## default + +### [POST] /apps/annotation-reply/{action} +**Configure Annotation Reply** + +Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| action | path | Action to perform: 'enable' or 'disable' | Yes | string,
**Available values:** "disable", "enable" | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [AnnotationReplyActionPayload](#annotationreplyactionpayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Annotation reply settings task initiated. | **application/json**: [AnnotationJobStatusResponse](#annotationjobstatusresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | + +### [GET] /apps/annotation-reply/{action}/status/{job_id} +**Get Annotation Reply Job Status** + +Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply). + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| action | path | Action type | Yes | string | +| job_id | path | Job ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successfully retrieved task status. | **application/json**: [AnnotationJobStatusResponse](#annotationjobstatusresponse)
| +| 400 | `invalid_param` : The specified job does not exist. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | Job not found | | + +### [GET] /apps/annotations +**List Annotations** + +Retrieves a paginated list of annotations for the application. Supports keyword search filtering. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| keyword | query | Keyword to search annotations | No | string | +| limit | query | Number of annotations per page | No | integer,
**Default:** 20 | +| page | query | Page number | No | integer,
**Default:** 1 | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successfully retrieved annotation list. | **application/json**: [AnnotationList](#annotationlist)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | + +### [POST] /apps/annotations +**Create Annotation** + +Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [AnnotationCreatePayload](#annotationcreatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 201 | Annotation created successfully. | **application/json**: [Annotation](#annotation)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | + +### [DELETE] /apps/annotations/{annotation_id} +**Delete Annotation** + +Deletes an annotation and its associated hit history. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| annotation_id | path | Annotation ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Annotation deleted successfully. | +| 401 | Unauthorized - invalid API token | +| 403 | `forbidden` : Insufficient permissions to edit annotations. | +| 404 | `not_found` : Annotation does not exist. | + +### [PUT] /apps/annotations/{annotation_id} +**Update Annotation** + +Updates the question and answer of an existing annotation. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| annotation_id | path | Annotation ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [AnnotationCreatePayload](#annotationcreatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Annotation updated successfully. | **application/json**: [Annotation](#annotation)
| +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : Insufficient permissions to edit annotations. | | +| 404 | `not_found` : Annotation does not exist. | | + +--- +## default + +### [POST] /audio-to-text +**Convert Audio to Text** + +Convert audio file to text. Supported MIME types: `audio/mp3`, `audio/mpga`, `audio/m4a`, `audio/wav`, and `audio/amr`. File size limit is `30 MB`. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **multipart/form-data**: { **"file"**: binary, **"user"**: string }
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successfully converted audio to text. | **application/json**: [AudioTranscriptResponse](#audiotranscriptresponse)
| +| 400 | - `app_unavailable` : App unavailable or misconfigured. - `provider_not_support_speech_to_text` : Model provider does not support speech-to-text. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model does not support this operation. - `completion_request_error` : Speech recognition request failed. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 413 | `audio_too_large` : Audio file size exceeded the limit. | | +| 415 | `unsupported_audio_type` : Audio type is not allowed. | | +| 500 | `internal_server_error` : Internal server error. | | + +### [POST] /text-to-audio +**Convert Text to Audio** + +Convert text to speech. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [TextToAudioPayloadWithUser](#texttoaudiopayloadwithuser)
| + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 200 | Returns the generated audio. Generator responses are streamed by the service as `audio/mpeg`; otherwise the provider output is returned directly. | +| 400 | - `app_unavailable` : App unavailable or misconfigured. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model does not support this operation. - `completion_request_error` : Text-to-speech request failed. | +| 401 | Unauthorized - invalid API token | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | +| 500 | `internal_server_error` : Internal server error. | + +--- +## default + +### [POST] /chat-messages +**Send Chat Message** + +Send a request to the chat application. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [ChatRequestPayloadWithUser](#chatrequestpayloadwithuser)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successful response. The content type and structure depend on the `response_mode` parameter in the request. - If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object. - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of Server-Sent Events. | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| +| 400 | - `app_unavailable` : App unavailable or misconfigured. - `not_chat_app` : App mode does not match the API route. - `conversation_completed` : The conversation has ended. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model unavailable. - `completion_request_error` : Text generation failed. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Conversation does not exist. | | +| 429 | - `too_many_requests` : Too many concurrent requests for this app. - `rate_limit_error` : The upstream model provider rate limit was exceeded. | | +| 500 | `internal_server_error` : Internal server error. | | + +### [POST] /chat-messages/{task_id}/stop +**Stop Chat Message Generation** + +Stops a chat message generation task. Only supported in `streaming` mode. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| task_id | path | The ID of the task to stop | Yes | string | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [RequiredServiceApiUserPayload](#requiredserviceapiuserpayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Task stopped successfully | **application/json**: [SimpleResultResponse](#simpleresultresponse)
| +| 400 | `not_chat_app` : App mode does not match the API route. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | Task not found | | ### [GET] /messages/{message_id}/suggested -**Get suggested follow-up questions for a message** +**Get Next Suggested Questions** -Get suggested follow-up questions for a message -Returns AI-generated follow-up questions based on the message content. +Get next questions suggestions for the current message. #### Parameters @@ -1746,80 +446,16 @@ Returns AI-generated follow-up questions based on the message content. | Code | Description | Schema | | ---- | ----------- | ------ | | 200 | Suggested questions retrieved successfully | **application/json**: [SimpleResultStringListResponse](#simpleresultstringlistresponse)
| -| 400 | Suggested questions feature is disabled | | +| 400 | - `not_chat_app` : App mode does not match the API route. - `bad_request` : Suggested questions feature is disabled. | | | 401 | Unauthorized - invalid API token | | | 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Message not found | | -| 500 | Internal server error | | - -### [GET] /meta -**Get app metadata** - -Get application metadata -Returns metadata about the application including configuration and settings. - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Metadata retrieved successfully | **application/json**: [AppMetaResponse](#appmetaresponse)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Application not found | | - -### [GET] /parameters -**Retrieve app parameters** - -Retrieve application input parameters and configuration -Returns the input form parameters and configuration for the application. - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Parameters retrieved successfully | **application/json**: [Parameters](#parameters)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Application not found | | - -### [GET] /site -**Retrieve app site info** - -Get application site configuration -Returns the site configuration for the application including theme, icons, and text. - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Site configuration retrieved successfully | **application/json**: [Site](#site)
| -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - site not found or tenant archived | | - -### [POST] /text-to-audio -**Convert text to audio using text-to-speech** - -Convert text to audio using text-to-speech -Converts the provided text to audio using the specified voice. - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [TextToAudioPayloadWithUser](#texttoaudiopayloadwithuser)
| - -#### Responses - -| Code | Description | -| ---- | ----------- | -| 200 | Text successfully converted to audio | -| 400 | Bad request - invalid parameters | -| 401 | Unauthorized - invalid API token | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | -| 500 | Internal server error | +| 404 | `not_found` : Message does not exist. | | +| 500 | `internal_server_error` : Internal server error. | | ### [GET] /workflow/{task_id}/events -Get workflow execution events stream after resume +**Stream Workflow Events** + +Resume 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. #### Parameters @@ -1834,16 +470,16 @@ Get workflow execution events stream after resume | Code | Description | Schema | | ---- | ----------- | ------ | -| 200 | SSE event stream | **text/event-stream**: [EventStreamResponse](#eventstreamresponse)
| +| 200 | Server-Sent Events stream. Each event is delivered as `data: {JSON}\\n\\n`. Event payloads follow the same schemas as the original streaming response. | **text/event-stream**: [EventStreamResponse](#eventstreamresponse)
| +| 400 | `not_workflow_app` : Please check if your app mode matches the right API route. | | | 401 | Unauthorized - invalid API token | | | 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Workflow run not found | | +| 404 | `not_found` : Workflow run not found. | | ### [GET] /workflows/logs -**Get workflow app logs** +**List Workflow Logs** -Get workflow execution logs -Returns paginated workflow execution logs with filtering options. +Retrieve paginated workflow execution logs with filtering options. #### Parameters @@ -1862,40 +498,14 @@ Returns paginated workflow execution logs with filtering options. | Code | Description | Schema | | ---- | ----------- | ------ | -| 200 | Logs retrieved successfully | **application/json**: [WorkflowAppLogPaginationResponse](#workflowapplogpaginationresponse)
| +| 200 | Successfully retrieved workflow logs. | **application/json**: [WorkflowAppLogPaginationResponse](#workflowapplogpaginationresponse)
| | 401 | Unauthorized - invalid API token | | | 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -### [POST] /workflows/run -**Execute a workflow** - -Execute a workflow -Runs a workflow with the provided inputs and returns the results. -Supports both blocking and streaming response modes. - -#### Request Body - -| Required | Schema | -| -------- | ------ | -| Yes | **application/json**: [WorkflowRunPayloadWithUser](#workflowrunpayloadwithuser)
| - -#### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Workflow executed successfully | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| -| 400 | Bad request - invalid parameters or workflow issues | | -| 401 | Unauthorized - invalid API token | | -| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Workflow not found | | -| 429 | Rate limit exceeded | | -| 500 | Internal server error | | - ### [GET] /workflows/run/{workflow_run_id} -**Get a workflow task running detail** +**Get Workflow Run Detail** -Get workflow run details -Returns detailed information about a specific workflow run. +Retrieve the current execution results of a workflow task based on the workflow execution ID. #### Parameters @@ -1907,13 +517,1744 @@ Returns detailed information about a specific workflow run. | Code | Description | Schema | | ---- | ----------- | ------ | -| 200 | Workflow run details retrieved successfully | **application/json**: [WorkflowRunResponse](#workflowrunresponse)
| +| 200 | Successfully retrieved workflow run details. | **application/json**: [WorkflowRunResponse](#workflowrunresponse)
| +| 400 | `not_workflow_app` : App mode does not match the API route. | | | 401 | Unauthorized - invalid API token | | | 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Workflow run not found | | +| 404 | `not_found` : Workflow run not found. | | + +--- +## default + +### [POST] /chat-messages +**Send Chat Message** + +Send a request to the chat application. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [ChatRequestPayloadWithUser](#chatrequestpayloadwithuser)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successful response. The content type and structure depend on the `response_mode` parameter in the request. - If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object. - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of Server-Sent Events. | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| +| 400 | - `app_unavailable` : App unavailable or misconfigured. - `not_chat_app` : App mode does not match the API route. - `conversation_completed` : The conversation has ended. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model unavailable. - `completion_request_error` : Text generation failed. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Conversation does not exist. | | +| 429 | - `too_many_requests` : Too many concurrent requests for this app. - `rate_limit_error` : The upstream model provider rate limit was exceeded. | | +| 500 | `internal_server_error` : Internal server error. | | + +### [POST] /chat-messages/{task_id}/stop +**Stop Chat Message Generation** + +Stops a chat message generation task. Only supported in `streaming` mode. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| task_id | path | The ID of the task to stop | Yes | string | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [RequiredServiceApiUserPayload](#requiredserviceapiuserpayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Task stopped successfully | **application/json**: [SimpleResultResponse](#simpleresultresponse)
| +| 400 | `not_chat_app` : App mode does not match the API route. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | Task not found | | + +### [GET] /messages/{message_id}/suggested +**Get Next Suggested Questions** + +Get next questions suggestions for the current message. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| message_id | path | Message ID | Yes | string (uuid) | +| user | query | End user identifier | Yes | string | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Suggested questions retrieved successfully | **application/json**: [SimpleResultStringListResponse](#simpleresultstringlistresponse)
| +| 400 | - `not_chat_app` : App mode does not match the API route. - `bad_request` : Suggested questions feature is disabled. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Message does not exist. | | +| 500 | `internal_server_error` : Internal server error. | | + +--- +## default + +### [POST] /completion-messages +**Send Completion Message** + +Send a request to the text generation application. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [CompletionRequestPayloadWithUser](#completionrequestpayloadwithuser)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successful response. The content type and structure depend on the `response_mode` parameter in the request. - If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` object. - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkCompletionEvent` objects. | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| +| 400 | - `app_unavailable` : App unavailable or misconfigured. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model unavailable. - `completion_request_error` : Text generation failed. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | Conversation not found | | +| 429 | `too_many_requests` : Too many concurrent requests for this app. | | +| 500 | `internal_server_error` : Internal server error. | | + +### [POST] /completion-messages/{task_id}/stop +**Stop Completion Message Generation** + +Stops a completion message generation task. Only supported in `streaming` mode. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| task_id | path | The ID of the task to stop | Yes | string | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [RequiredServiceApiUserPayload](#requiredserviceapiuserpayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Task stopped successfully | **application/json**: [SimpleResultResponse](#simpleresultresponse)
| +| 400 | `app_unavailable` : App unavailable or misconfigured. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | Task not found | | + +--- +## default + +### [GET] /conversations +**List Conversations** + +Retrieve the conversation list for the current user, ordered by most recently active. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| last_id | query | Last conversation ID for pagination | No | string | +| limit | query | Number of conversations to return | No | integer,
**Default:** 20 | +| sort_by | query | Sort order for conversations | No | string,
**Available values:** "-created_at", "-updated_at", "created_at", "updated_at",
**Default:** -updated_at | +| user | query | End user identifier | No | string | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successfully retrieved conversations list. | **application/json**: [ConversationInfiniteScrollPagination](#conversationinfinitescrollpagination)
| +| 400 | `not_chat_app` : App mode does not match the API route. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Last conversation does not exist (invalid `last_id`). | | + +### [DELETE] /conversations/{c_id} +**Delete Conversation** + +Delete a conversation. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| c_id | path | Conversation ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [OptionalServiceApiUserPayload](#optionalserviceapiuserpayload)
| + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Conversation deleted successfully. | +| 400 | `not_chat_app` : App mode does not match the API route. | +| 401 | Unauthorized - invalid API token | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | +| 404 | `not_found` : Conversation does not exist. | + +### [POST] /conversations/{c_id}/name +**Rename Conversation** + +Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| c_id | path | Conversation ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [ConversationRenamePayloadWithUser](#conversationrenamepayloadwithuser)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Conversation renamed successfully. | **application/json**: [SimpleConversation](#simpleconversation)
| +| 400 | `not_chat_app` : App mode does not match the API route. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Conversation does not exist. | | + +### [GET] /conversations/{c_id}/variables +**List Conversation Variables** + +Retrieve variables from a specific conversation. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| c_id | path | Conversation ID | Yes | string (uuid) | +| last_id | query | Last variable ID for pagination | No | string | +| limit | query | Number of variables to return | No | integer,
**Default:** 20 | +| user | query | End user identifier | No | string | +| variable_name | query | Filter variables by name | No | string | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successfully retrieved conversation variables. | **application/json**: [ConversationVariableInfiniteScrollPaginationResponse](#conversationvariableinfinitescrollpaginationresponse)
| +| 400 | `not_chat_app` : App mode does not match the API route. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Conversation does not exist. | | + +### [PUT] /conversations/{c_id}/variables/{variable_id} +**Update Conversation Variable** + +Update the value of a specific conversation variable. The value must match the expected type. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| c_id | path | Conversation ID | Yes | string (uuid) | +| variable_id | path | Variable ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [ConversationVariableUpdatePayloadWithUser](#conversationvariableupdatepayloadwithuser)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Variable updated successfully. | **application/json**: [ConversationVariableResponse](#conversationvariableresponse)
| +| 400 | - `not_chat_app` : App mode does not match the API route. - `bad_request` : Variable value type mismatch. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | - `not_found` : Conversation does not exist. - `not_found` : Conversation variable does not exist. | | + +### [GET] /messages +**List Conversation Messages** + +Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| conversation_id | query | Conversation UUID | Yes | string | +| first_id | query | First message ID for pagination | No | string | +| limit | query | Number of messages to return (1-100) | No | integer,
**Default:** 20 | +| user | query | End user identifier | No | string | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successfully retrieved conversation history. | **application/json**: [MessageInfiniteScrollPagination](#messageinfinitescrollpagination)
| +| 400 | `not_chat_app` : App mode does not match the API route. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | - `not_found` : Conversation does not exist. - `not_found` : First message does not exist. | | + +--- +## default + +### [GET] /datasets +**List Knowledge Bases** + +Returns a paginated list of knowledge bases. Supports filtering by keyword and tags. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| include_all | query | Include all datasets | No | boolean | +| keyword | query | Search keyword | No | string | +| limit | query | Number of items per page | No | integer,
**Default:** 20 | +| page | query | Page number | No | integer,
**Default:** 1 | +| tag_ids | query | Filter by tag IDs | No | [ string ] | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | List of knowledge bases. | **application/json**: [DatasetListResponse](#datasetlistresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | + +### [POST] /datasets +**Create an Empty Knowledge Base** + +Create a new empty knowledge base. After creation, use [Create Document by Text](/api-reference/documents/create-document-by-text) or [Create Document by File](/api-reference/documents/create-document-by-file) to add documents. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [DatasetCreatePayload](#datasetcreatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Knowledge base created successfully. | **application/json**: [DatasetDetailResponse](#datasetdetailresponse)
| +| 400 | Bad request - invalid parameters | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 409 | `dataset_name_duplicate` : The dataset name already exists. Please modify your dataset name. | | + +### [DELETE] /datasets/{dataset_id} +**Delete Knowledge Base** + +Permanently delete a knowledge base and all its documents. The knowledge base must not be in use by any application. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Success. | +| 401 | Unauthorized - invalid API token | +| 403 | Forbidden - dataset API access or workspace access denied | +| 404 | `not_found` : Dataset not found. | +| 409 | `dataset_in_use` : The knowledge base is being used by some apps. Please remove it from the apps before deleting. | + +### [GET] /datasets/{dataset_id} +**Get Knowledge Base** + +Retrieve detailed information about a specific knowledge base, including its embedding model, retrieval configuration, and document statistics. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Knowledge base details. | **application/json**: [DatasetDetailWithPartialMembersResponse](#datasetdetailwithpartialmembersresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : Insufficient permissions to access this knowledge base. | | +| 404 | `not_found` : Dataset not found. | | + +### [PATCH] /datasets/{dataset_id} +**Update Knowledge Base** + +Update the name, description, permissions, or retrieval settings of an existing knowledge base. Only the fields provided in the request body are updated. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [DatasetUpdatePayload](#datasetupdatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Knowledge base updated successfully. | **application/json**: [DatasetDetailWithPartialMembersResponse](#datasetdetailwithpartialmembersresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : Insufficient permissions to access this knowledge base. | | +| 404 | `not_found` : Dataset not found. | | + +### [POST] /datasets/{dataset_id}/hit-testing +**Retrieve Chunks from a Knowledge Base / Test Retrieval** + +Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used for both production retrieval and test retrieval. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [HitTestingPayload](#hittestingpayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Retrieval results. | **application/json**: [HitTestingResponse](#hittestingresponse)
| +| 400 | - `dataset_not_initialized` : The dataset is still being initialized or indexing. Please wait a moment. - `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. - `provider_quota_exceeded` : 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` : Dify Hosted OpenAI trial currently not support the GPT-4 model. - `completion_request_error` : Completion request failed. - `invalid_param` : Invalid parameter value. | | +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : Insufficient permissions. | | +| 404 | `not_found` : Knowledge base not found. | | +| 500 | `internal_server_error` : An internal error occurred during retrieval. | | + +### [POST] /datasets/{dataset_id}/retrieve +**Retrieve Chunks from a Knowledge Base / Test Retrieval** + +Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used for both production retrieval and test retrieval. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [HitTestingPayload](#hittestingpayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Retrieval results. | **application/json**: [HitTestingResponse](#hittestingresponse)
| +| 400 | - `dataset_not_initialized` : The dataset is still being initialized or indexing. Please wait a moment. - `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. - `provider_quota_exceeded` : 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` : Dify Hosted OpenAI trial currently not support the GPT-4 model. - `completion_request_error` : Completion request failed. - `invalid_param` : Invalid parameter value. | | +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : Insufficient permissions. | | +| 404 | `not_found` : Knowledge base not found. | | +| 500 | `internal_server_error` : An internal error occurred during retrieval. | | + +--- +## default + +### [POST] /datasets/pipeline/file-upload +**Upload Pipeline File** + +Upload a file for use in a knowledge pipeline. Accepts a single file via `multipart/form-data`. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **multipart/form-data**: { **"file"**: binary }
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 201 | File uploaded successfully. | **application/json**: [PipelineUploadFileResponse](#pipelineuploadfileresponse)
| +| 400 | - `no_file_uploaded` : Please upload your file. - `filename_not_exists_error` : The specified filename does not exist. - `too_many_files` : Only one file is allowed. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 413 | `file_too_large` : File size exceeded. | | +| 415 | `unsupported_file_type` : File type not allowed. | | + +### [GET] /datasets/{dataset_id}/pipeline/datasource-plugins +**List Datasource Plugins** + +List the datasource nodes configured in the knowledge pipeline. Each node includes the plugin it uses plus the metadata needed to run it. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| is_published | query | | No | boolean,
**Default:** true | +| dataset_id | path | | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | List of datasource nodes configured in the pipeline. | **application/json**: [DatasourcePluginListResponse](#datasourcepluginlistresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | `not_found` : Dataset not found. | | + +### [POST] /datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run +**Run Datasource Node** + +Execute a single datasource node within the knowledge pipeline. Returns a streaming response with the node execution results. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | | Yes | string (uuid) | +| node_id | path | | Yes | string | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [DatasourceNodeRunPayload](#datasourcenoderunpayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Streaming response with node execution events. | **text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | `not_found` : Dataset not found. | | + +### [POST] /datasets/{dataset_id}/pipeline/run +**Run Pipeline** + +Execute the full knowledge pipeline for a knowledge base. Supports both streaming and blocking response modes. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [PipelineRunApiEntity](#pipelinerunapientity)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Pipeline execution result. Format depends on `response_mode`: streaming returns a `text/event-stream`, blocking returns a JSON object. | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : Forbidden. | | +| 404 | `not_found` : Dataset not found. | | +| 500 | `pipeline_run_error` : Pipeline execution failed. | | + +--- +## default + +### [DELETE] /datasets/tags +**Delete Knowledge Tag** + +Permanently delete a knowledge base tag. Does not delete the knowledge bases that were tagged. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [TagDeletePayload](#tagdeletepayload)
| + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Success. | +| 401 | Unauthorized - invalid API token | +| 403 | Forbidden - insufficient permissions | + +### [GET] /datasets/tags +**List Knowledge Tags** + +Returns the list of all knowledge base tags in the workspace. + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | List of tags. | **application/json**: [KnowledgeTagListResponse](#knowledgetaglistresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | + +### [PATCH] /datasets/tags +**Update Knowledge Tag** + +Rename an existing knowledge base tag. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [TagUpdatePayload](#tagupdatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Tag updated successfully. | **application/json**: [KnowledgeTagResponse](#knowledgetagresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - insufficient permissions | | + +### [POST] /datasets/tags +**Create Knowledge Tag** + +Create a new tag for organizing knowledge bases. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [TagCreatePayload](#tagcreatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Tag created successfully. | **application/json**: [KnowledgeTagResponse](#knowledgetagresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - insufficient permissions | | + +### [POST] /datasets/tags/binding +**Create Tag Binding** + +Bind one or more tags to a knowledge base. A knowledge base can have multiple tags. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [TagBindingPayload](#tagbindingpayload)
| + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Success. | +| 401 | Unauthorized - invalid API token | +| 403 | Forbidden - insufficient permissions | + +### [POST] /datasets/tags/unbinding +**Delete Tag Binding** + +Remove one or more tags from a knowledge base. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [TagUnbindingPayload](#tagunbindingpayload)
| + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Success. | +| 401 | Unauthorized - invalid API token | +| 403 | Forbidden - insufficient permissions | + +### [GET] /datasets/{dataset_id}/tags +**Get Knowledge Base Tags** + +Returns the list of tags bound to a specific knowledge base. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Tags bound to the knowledge base. | **application/json**: [DatasetBoundTagListResponse](#datasetboundtaglistresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | + +--- +## default + +### [POST] /datasets/{dataset_id}/document/create-by-file +**Create Document by File** + +Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **multipart/form-data**: { **"data"**: string, **"file"**: binary }
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document created successfully. | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| +| 400 | - `no_file_uploaded` : Please upload your file. - `too_many_files` : Only one file is allowed. - `filename_not_exists_error` : The specified filename does not exist. - `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. - `invalid_param` : Knowledge base does not exist, external datasets not supported, file too large, unsupported file type, missing required fields, or invalid doc_form (must be `text_model`, `hierarchical_model`, or `qa_model`). | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | + +### [POST] /datasets/{dataset_id}/document/create-by-text +**Create Document by Text** + +Create a document from raw text content. The document is processed asynchronously — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [DocumentTextCreatePayload](#documenttextcreatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document created successfully. | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| +| 400 | - `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. - `invalid_param` : Knowledge base does not exist. / indexing_technique is required. / Invalid doc_form (must be `text_model`, `hierarchical_model`, or `qa_model`). | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | + +### ~~[POST] /datasets/{dataset_id}/document/create_by_file~~ + +***DEPRECATED*** + +**Create Document by File** + +Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **multipart/form-data**: { **"data"**: string, **"file"**: binary }
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document created successfully. | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| +| 400 | - `no_file_uploaded` : Please upload your file. - `too_many_files` : Only one file is allowed. - `filename_not_exists_error` : The specified filename does not exist. - `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. - `invalid_param` : Knowledge base does not exist, external datasets not supported, file too large, unsupported file type, missing required fields, or invalid doc_form (must be `text_model`, `hierarchical_model`, or `qa_model`). | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | + +### [GET] /datasets/{dataset_id}/documents +**List Documents** + +Returns a paginated list of documents in the knowledge base. Supports filtering by keyword and indexing status. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| keyword | query | Search keyword | No | string | +| limit | query | Number of items per page | No | integer,
**Default:** 20 | +| page | query | Page number | No | integer,
**Default:** 1 | +| status | query | Document status filter | No | string | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | List of documents. | **application/json**: [DocumentListResponse](#documentlistresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | `not_found` : Knowledge base not found. | | + +### [POST] /datasets/{dataset_id}/documents/download-zip +**Download Documents as ZIP** + +Download multiple uploaded-file documents as a single ZIP archive. Accepts up to `100` document IDs. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [DocumentBatchDownloadZipPayload](#documentbatchdownloadzippayload)
| + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 200 | ZIP archive containing the requested documents. | +| 401 | Unauthorized - invalid API token | +| 403 | `forbidden` : Insufficient permissions. | +| 404 | `not_found` : Document or dataset not found. | + +### [PATCH] /datasets/{dataset_id}/documents/status/{action} +**Update Document Status in Batch** + +Enable, disable, archive, or unarchive multiple documents at once. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| action | path | Action to perform: 'enable', 'disable', 'archive', or 'un_archive' | Yes | string,
**Available values:** "archive", "disable", "enable", "un_archive" | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [DocumentStatusPayload](#documentstatuspayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document status updated successfully | **application/json**: [SimpleResultResponse](#simpleresultresponse)
| +| 400 | `invalid_action` : Invalid action. | | +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : Insufficient permissions. | | +| 404 | `not_found` : Knowledge base not found. | | + +### [GET] /datasets/{dataset_id}/documents/{batch}/indexing-status +**Get Document Indexing Status** + +Check the indexing progress of documents in a batch. Returns the current processing stage and chunk completion counts for each document. Poll this endpoint until `indexing_status` reaches `completed` or `error`. The status progresses through: `waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| batch | path | Batch ID | Yes | string | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Indexing status for documents in the batch. | **application/json**: [DocumentStatusListResponse](#documentstatuslistresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | `not_found` : Knowledge base not found. / Documents not found. | | + +### [DELETE] /datasets/{dataset_id}/documents/{document_id} +**Delete Document** + +Permanently delete a document and all its chunks from the knowledge base. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Success. | +| 400 | `document_indexing` : Cannot delete document during indexing. | +| 401 | Unauthorized - invalid API token | +| 403 | `archived_document_immutable` : The archived document is not editable. | +| 404 | `not_found` : Document Not Exists. | + +### [GET] /datasets/{dataset_id}/documents/{document_id} +**Get Document** + +Retrieve detailed information about a specific document, including its indexing status, metadata, and processing statistics. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | +| metadata | query | Metadata response mode | No | string,
**Available values:** "all", "only", "without",
**Default:** all | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document details. The response shape varies based on the `metadata` query parameter. When `metadata` is `only`, only `id`, `doc_type`, and `doc_metadata` are returned. When `metadata` is `without`, `doc_type` and `doc_metadata` are omitted. | **application/json**: [DocumentDetailResponse](#documentdetailresponse)
| +| 400 | `invalid_metadata` : Invalid metadata value for the specified key. | | +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : No permission. | | +| 404 | `not_found` : Document not found. | | + +### [PATCH] /datasets/{dataset_id}/documents/{document_id} +Update an existing document by uploading a file + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| No | **multipart/form-data**: { **"data"**: string, **"file"**: binary }
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document updated successfully | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Document not found | | + +### [GET] /datasets/{dataset_id}/documents/{document_id}/download +**Download Document** + +Get a signed download URL for a document's original uploaded file. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Download URL generated successfully. | **application/json**: [UrlResponse](#urlresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : No permission to access this document. | | +| 404 | `not_found` : Document not found. | | + +### ~~[POST] /datasets/{dataset_id}/documents/{document_id}/update-by-file~~ + +***DEPRECATED*** + +**Update Document by File** + +Update an existing document by uploading a new file. Re-triggers indexing — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| No | **multipart/form-data**: { **"data"**: string, **"file"**: binary }
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document updated successfully. | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| +| 400 | - `too_many_files` : Only one file is allowed. - `filename_not_exists_error` : The specified filename does not exist. - `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. - `invalid_param` : Knowledge base does not exist, external datasets not supported, file too large, unsupported file type, or invalid doc_form (must be `text_model`, `hierarchical_model`, or `qa_model`). | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Document not found | | + +### [POST] /datasets/{dataset_id}/documents/{document_id}/update-by-text +**Update Document by Text** + +Update an existing document's text content, name, or processing configuration. Re-triggers indexing if content changes — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [DocumentTextUpdate](#documenttextupdate)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document updated successfully. | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| +| 400 | - `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. - `invalid_param` : Knowledge base does not exist, name is required when text is provided, or invalid doc_form (must be `text_model`, `hierarchical_model`, or `qa_model`). | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Document not found | | + +### ~~[POST] /datasets/{dataset_id}/documents/{document_id}/update_by_file~~ + +***DEPRECATED*** + +**Update Document by File** + +Update an existing document by uploading a new file. Re-triggers indexing — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| No | **multipart/form-data**: { **"data"**: string, **"file"**: binary }
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document updated successfully. | **application/json**: [DocumentAndBatchResponse](#documentandbatchresponse)
| +| 400 | - `too_many_files` : Only one file is allowed. - `filename_not_exists_error` : The specified filename does not exist. - `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. - `invalid_param` : Knowledge base does not exist, external datasets not supported, file too large, unsupported file type, or invalid doc_form (must be `text_model`, `hierarchical_model`, or `qa_model`). | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Document not found | | + +--- +## default + +### [POST] /datasets/{dataset_id}/documents/metadata +**Update Document Metadata in Batch** + +Update metadata values for multiple documents at once. Each document in the request receives the specified metadata key-value pairs. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [MetadataOperationData](#metadataoperationdata)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Document metadata updated successfully. | **application/json**: [DatasetMetadataActionResponse](#datasetmetadataactionresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset not found | | + +### [GET] /datasets/{dataset_id}/metadata +**List Metadata Fields** + +Returns the list of all metadata fields (both custom and built-in) for the knowledge base, along with the count of documents using each field. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Metadata fields for the knowledge base. | **application/json**: [DatasetMetadataListResponse](#datasetmetadatalistresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset not found | | + +### [POST] /datasets/{dataset_id}/metadata +**Create Metadata Field** + +Create a custom metadata field for the knowledge base. Metadata fields can be used to annotate documents with structured information. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [MetadataArgs](#metadataargs)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 201 | Metadata field created successfully. | **application/json**: [DatasetMetadataResponse](#datasetmetadataresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset not found | | + +### [GET] /datasets/{dataset_id}/metadata/built-in +**Get Built-in Metadata Fields** + +Returns the list of built-in metadata fields provided by the system (e.g., document type, source URL). + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Built-in metadata fields. | **application/json**: [DatasetMetadataBuiltInFieldsResponse](#datasetmetadatabuiltinfieldsresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | + +### [POST] /datasets/{dataset_id}/metadata/built-in/{action} +**Update Built-in Metadata Field** + +Enable or disable built-in metadata fields for the knowledge base. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| action | path | Action to perform: 'enable' or 'disable' | Yes | string,
**Available values:** "disable", "enable" | +| dataset_id | path | Dataset ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Built-in metadata field toggled successfully. | **application/json**: [DatasetMetadataActionResponse](#datasetmetadataactionresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset not found | | + +### [DELETE] /datasets/{dataset_id}/metadata/{metadata_id} +**Delete Metadata Field** + +Permanently delete a custom metadata field. Documents using this field will lose their metadata values for it. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| metadata_id | path | Metadata ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Success. | +| 401 | Unauthorized - invalid API token | +| 403 | Forbidden - dataset API access or workspace access denied | +| 404 | Dataset or metadata not found | + +### [PATCH] /datasets/{dataset_id}/metadata/{metadata_id} +**Update Metadata Field** + +Rename a custom metadata field. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| metadata_id | path | Metadata ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [MetadataUpdatePayload](#metadataupdatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Metadata field updated successfully. | **application/json**: [DatasetMetadataResponse](#datasetmetadataresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset or metadata not found | | + +--- +## default + +### [GET] /datasets/{dataset_id}/documents/{document_id}/segments +**List Chunks** + +Returns a paginated list of chunks within a document. Supports filtering by keyword and status. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | +| keyword | query | | No | string | +| limit | query | | No | integer,
**Default:** 20 | +| page | query | | No | integer,
**Default:** 1 | +| status | query | | No | [ string ] | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | List of chunks. | **application/json**: [SegmentListResponse](#segmentlistresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset or document not found | | + +### [POST] /datasets/{dataset_id}/documents/{document_id}/segments +**Create Chunks** + +Create one or more chunks within a document. Each chunk can include optional keywords and an answer field (for QA-mode documents). + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [SegmentCreatePayload](#segmentcreatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Chunks created successfully. | **application/json**: [SegmentCreateListResponse](#segmentcreatelistresponse)
| +| 400 | Bad request - segments data is missing | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | `not_found` : Document is not completed or is disabled. | | + +### [DELETE] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id} +**Delete Chunk** + +Permanently delete a chunk from the document. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | +| segment_id | path | Segment ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Success. | +| 401 | Unauthorized - invalid API token | +| 403 | Forbidden - dataset API access or workspace access denied | +| 404 | Dataset, document, or segment not found | + +### [GET] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id} +**Get Chunk** + +Retrieve detailed information about a specific chunk, including its content, keywords, and indexing status. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | +| segment_id | path | Segment ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Chunk details. | **application/json**: [SegmentDetailResponse](#segmentdetailresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset, document, or segment not found | | + +### [POST] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id} +**Update Chunk** + +Update a chunk's content, keywords, or answer. Re-triggers indexing for the modified chunk. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | +| segment_id | path | Segment ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [SegmentUpdatePayload](#segmentupdatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Chunk updated successfully. | **application/json**: [SegmentDetailResponse](#segmentdetailresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset, document, or segment not found | | + +### [GET] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks +**List Child Chunks** + +Returns a paginated list of child chunks under a specific parent chunk. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | +| segment_id | path | Parent segment ID | Yes | string (uuid) | +| keyword | query | | No | string | +| limit | query | | No | integer,
**Default:** 20 | +| page | query | | No | integer,
**Default:** 1 | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | List of child chunks. | **application/json**: [ChildChunkListResponse](#childchunklistresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset, document, or segment not found | | + +### [POST] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks +**Create Child Chunk** + +Create a child chunk under the specified segment. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | +| segment_id | path | Parent segment ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [ChildChunkCreatePayload](#childchunkcreatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Child chunk created successfully. | **application/json**: [ChildChunkDetailResponse](#childchunkdetailresponse)
| +| 400 | `invalid_param` : Create child chunk index failed. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset, document, or segment not found | | + +### [DELETE] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id} +**Delete Child Chunk** + +Permanently delete a child chunk from its parent chunk. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| child_chunk_id | path | Child chunk ID | Yes | string (uuid) | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | +| segment_id | path | Parent segment ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 204 | Success. | +| 400 | `invalid_param` : Delete child chunk index failed. | +| 401 | Unauthorized - invalid API token | +| 403 | Forbidden - dataset API access or workspace access denied | +| 404 | Dataset, document, segment, or child chunk not found | + +### [PATCH] /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id} +**Update Child Chunk** + +Update the content of an existing child chunk. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| child_chunk_id | path | Child chunk ID | Yes | string (uuid) | +| dataset_id | path | Dataset ID | Yes | string (uuid) | +| document_id | path | Document ID | Yes | string (uuid) | +| segment_id | path | Parent segment ID | Yes | string (uuid) | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [ChildChunkUpdatePayload](#childchunkupdatepayload)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Child chunk updated successfully. | **application/json**: [ChildChunkDetailResponse](#childchunkdetailresponse)
| +| 400 | `invalid_param` : Update child chunk index failed. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - dataset API access or workspace access denied | | +| 404 | Dataset, document, segment, or child chunk not found | | + +--- +## default + +### [GET] /end-users/{end_user_id} +**Get End User Info** + +Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)). + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| end_user_id | path | End user ID | Yes | string (uuid) | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | End user retrieved successfully. | **application/json**: [EndUserDetail](#enduserdetail)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `end_user_not_found` : End user not found. | | + +--- +## default + +### [POST] /files/upload +**Upload File** + +Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **multipart/form-data**: { **"file"**: binary, **"user"**: string }
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 201 | File uploaded successfully. | **application/json**: [FileResponse](#fileresponse)
| +| 400 | - `no_file_uploaded` : No file was provided in the request. - `too_many_files` : Only one file is allowed per request. - `filename_not_exists_error` : The uploaded file has no filename. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 413 | `file_too_large` : File size exceeded. | | +| 415 | `unsupported_file_type` : File type not allowed. | | + +### [GET] /files/{file_id}/preview +**Download File** + +Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| file_id | path | UUID of the file to preview | Yes | string (uuid) | +| as_attachment | query | Download as attachment | No | boolean | +| user | query | End user identifier | No | string | + +#### Responses + +| Code | Description | +| ---- | ----------- | +| 200 | 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`. | +| 401 | Unauthorized - invalid API token | +| 403 | `file_access_denied` : Access to the requested file is denied. | +| 404 | `file_not_found` : The requested file was not found. | + +--- +## default + +### [GET] /form/human_input/{form_token} +**Get Human Input Form** + +Retrieve a paused Human Input form's contents using the `form_token` from a `human_input_required` event. Requires **WebApp** delivery. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| form_token | path | Human input form token | Yes | string | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Form contents retrieved successfully. | **application/json**: [HumanInputFormDefinitionResponse](#humaninputformdefinitionresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Form not found. | | +| 412 | - `human_input_form_submitted` : Form already submitted. Forms are one-shot; the first response wins regardless of which user submits it. - `human_input_form_expired` : The form's expiration time passed before submission arrived. | | + +### [POST] /form/human_input/{form_token} +**Submit Human Input Form** + +Submit the recipient's response to a paused Human Input form. The workflow resumes on acceptance; use [Stream Workflow Events](/api-reference/chatflows/stream-workflow-events) to follow subsequent events. Requires **WebApp** delivery. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| form_token | path | Human input form token | Yes | string | + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [HumanInputFormSubmitPayloadWithUser](#humaninputformsubmitpayloadwithuser)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Form submitted successfully. The response body is an empty object. | **application/json**: [HumanInputFormSubmitResponse](#humaninputformsubmitresponse)
| +| 400 | - `bad_request` : Form recipient type is invalid. - `invalid_form_data` : Submission failed validation against the form definition. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Form not found. | | +| 412 | - `human_input_form_submitted` : Form already submitted. Forms are one-shot; the first response wins regardless of which user submits it. - `human_input_form_expired` : The form's expiration time passed before submission arrived. | | + +--- +## default + +### [GET] /info +**Get App Info** + +Retrieve basic information about this application, including name, description, tags, and mode. + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Basic information of the application. | **application/json**: [AppInfoResponse](#appinforesponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | Application not found | | + +### [GET] /meta +**Get App Meta** + +Retrieve metadata about this application, including tool icons and other configuration details. + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successfully retrieved application meta information. | **application/json**: [AppMetaResponse](#appmetaresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | Application not found | | + +### [GET] /parameters +**Get App Parameters** + +Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values. + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Application parameters information. | **application/json**: [Parameters](#parameters)
| +| 400 | `app_unavailable` : App unavailable or misconfigured. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | Application not found | | + +### [GET] /site +**Get App WebApp Settings** + +Retrieve the WebApp settings of this application, including site configuration, theme, and customization options. + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | WebApp settings of the application. | **application/json**: [Site](#site)
| +| 401 | Unauthorized - invalid API token | | +| 403 | `forbidden` : Site not found for this application or the workspace has been archived. | | + +--- +## default + +### [GET] /workflow/{task_id}/events +**Stream Workflow Events** + +Resume 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. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| task_id | path | Workflow run ID | Yes | string | +| continue_on_pause | query | Keep the stream open across workflow_paused events | No | boolean | +| include_state_snapshot | query | Replay from persisted state snapshot | No | boolean | +| user | query | End user identifier | Yes | string | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Server-Sent Events stream. Each event is delivered as `data: {JSON}\\n\\n`. Event payloads follow the same schemas as the original streaming response. | **text/event-stream**: [EventStreamResponse](#eventstreamresponse)
| +| 400 | `not_workflow_app` : Please check if your app mode matches the right API route. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Workflow run not found. | | + +### [GET] /workflows/logs +**List Workflow Logs** + +Retrieve paginated workflow execution logs with filtering options. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| created_at__after | query | | No | string | +| created_at__before | query | | No | string | +| created_by_account | query | | No | string | +| created_by_end_user_session_id | query | | No | string | +| keyword | query | | No | string | +| limit | query | | No | integer,
**Default:** 20 | +| page | query | | No | integer,
**Default:** 1 | +| status | query | | No | string,
**Available values:** "failed", "stopped", "succeeded" | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successfully retrieved workflow logs. | **application/json**: [WorkflowAppLogPaginationResponse](#workflowapplogpaginationresponse)
| +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | + +### [POST] /workflows/run +**Run Workflow** + +Execute a workflow. Cannot be executed without a published workflow. + +#### Request Body + +| Required | Schema | +| -------- | ------ | +| Yes | **application/json**: [WorkflowRunPayloadWithUser](#workflowrunpayloadwithuser)
| + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successful response. The content type and structure depend on the `response_mode` parameter in the request. - If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object. - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects. | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| +| 400 | - `not_workflow_app` : App mode does not match the API route. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model unavailable. - `completion_request_error` : Workflow execution request failed. - `invalid_param` : Invalid parameter value. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | Workflow not found | | +| 429 | - `too_many_requests` : Too many concurrent requests for this app. - `rate_limit_error` : The upstream model provider rate limit was exceeded. | | +| 500 | `internal_server_error` : Internal server error. | | + +### [GET] /workflows/run/{workflow_run_id} +**Get Workflow Run Detail** + +Retrieve the current execution results of a workflow task based on the workflow execution ID. + +#### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ------ | +| workflow_run_id | path | Workflow run ID | Yes | string | + +#### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Successfully retrieved workflow run details. | **application/json**: [WorkflowRunResponse](#workflowrunresponse)
| +| 400 | `not_workflow_app` : App mode does not match the API route. | | +| 401 | Unauthorized - invalid API token | | +| 403 | Forbidden - token scope, app, dataset, or workspace access denied | | +| 404 | `not_found` : Workflow run not found. | | ### [POST] /workflows/tasks/{task_id}/stop -**Stop a running workflow task** +**Stop Workflow Task** + +Stop a running workflow task. Only supported in `streaming` mode. #### Parameters @@ -1932,15 +2273,15 @@ Returns detailed information about a specific workflow run. | Code | Description | Schema | | ---- | ----------- | ------ | | 200 | Task stopped successfully | **application/json**: [SimpleResultResponse](#simpleresultresponse)
| +| 400 | - `not_workflow_app` : App mode does not match the API route. - `invalid_param` : Required parameter missing or invalid. | | | 401 | Unauthorized - invalid API token | | | 403 | Forbidden - token scope, app, dataset, or workspace access denied | | | 404 | Task not found | | ### [POST] /workflows/{workflow_id}/run -**Run specific workflow by ID** +**Run Workflow by ID** -Execute a specific workflow by ID -Executes a specific workflow version identified by its ID. +Execute a specific workflow version identified by its ID. Useful for running a particular published version of the workflow. #### Parameters @@ -1958,19 +2299,21 @@ Executes a specific workflow version identified by its ID. | Code | Description | Schema | | ---- | ----------- | ------ | -| 200 | Workflow executed successfully | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| -| 400 | Bad request - invalid parameters or workflow issues | | +| 200 | Successful response. The content type and structure depend on the `response_mode` parameter in the request. - If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object. - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects. | **application/json**: [GeneratedAppResponse](#generatedappresponse)
**text/event-stream**: [GeneratedAppResponse](#generatedappresponse)
| +| 400 | - `not_workflow_app` : App mode does not match the API route. - `bad_request` : Workflow is a draft or has an invalid ID format. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model unavailable. - `completion_request_error` : Workflow execution request failed. - `invalid_param` : Required parameter missing or invalid. | | | 401 | Unauthorized - invalid API token | | | 403 | Forbidden - token scope, app, dataset, or workspace access denied | | -| 404 | Workflow not found | | -| 429 | Rate limit exceeded | | -| 500 | Internal server error | | +| 404 | `not_found` : Workflow not found. | | +| 429 | - `too_many_requests` : Too many concurrent requests for this app. - `rate_limit_error` : The upstream model provider rate limit was exceeded. | | +| 500 | `internal_server_error` : Internal server error. | | + +--- +## default ### [GET] /workspaces/current/models/model-types/{model_type} -**Get available models by model type** +**Get Available Models** -Get available models by model type -Returns a list of available models for the specified model type. +Retrieve the list of available models by type. Primarily used to query `text-embedding` and `rerank` models for knowledge base configuration. #### Parameters @@ -1982,7 +2325,7 @@ Returns a list of available models for the specified model type. | Code | Description | Schema | | ---- | ----------- | ------ | -| 200 | Models retrieved successfully | **application/json**: [ProviderWithModelsListResponse](#providerwithmodelslistresponse)
| +| 200 | Available models for the specified type. | **application/json**: [ProviderWithModelsListResponse](#providerwithmodelslistresponse)
| | 401 | Unauthorized - invalid API token | | --- @@ -3732,7 +4075,7 @@ Accepts either the legacy tag_id payload or the normalized tag_ids payload. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | message_id | string | Message ID | No | -| streaming | boolean | Enable streaming response | No | +| streaming | boolean | Reserved for compatibility; TTS response streaming is determined by the provider output. | No | | text | string | Text to convert to audio | No | | voice | string | Voice to use for TTS | No | @@ -3741,7 +4084,7 @@ Accepts either the legacy tag_id payload or the normalized tag_ids payload. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | message_id | string | Message ID | No | -| streaming | boolean | Enable streaming response | No | +| streaming | boolean | Reserved for compatibility; TTS response streaming is determined by the provider output. | No | | text | string | Text to convert to audio | No | | user | string | End user identifier | No | | voice | string | Voice to use for TTS | No | diff --git a/api/openapi/markdown/web-openapi.md b/api/openapi/markdown/web-openapi.md index d3cce8462a1..33f73dca648 100644 --- a/api/openapi/markdown/web-openapi.md +++ b/api/openapi/markdown/web-openapi.md @@ -1632,7 +1632,7 @@ Default configuration for form inputs. | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | | message_id | string | Message ID | No | -| streaming | boolean | Enable streaming response | No | +| streaming | boolean | Reserved for compatibility; TTS response streaming is determined by the provider output. | No | | text | string | Text to convert to audio | No | | voice | string | Voice to use for TTS | No | diff --git a/api/tests/unit_tests/commands/test_generate_swagger_specs.py b/api/tests/unit_tests/commands/test_generate_swagger_specs.py index 7f68222ceaa..d333dd50ea7 100644 --- a/api/tests/unit_tests/commands/test_generate_swagger_specs.py +++ b/api/tests/unit_tests/commands/test_generate_swagger_specs.py @@ -106,6 +106,22 @@ def test_generate_specs_writes_get_operations_without_request_bodies(tmp_path): assert all("requestBody" not in operation for operation in _get_operations(payload)) +def test_generate_specs_writes_service_api_reference_descriptions(tmp_path): + module = _load_generate_swagger_specs_module() + + written_paths = module.generate_specs(tmp_path) + service_path = next(path for path in written_paths if path.name == "service-openapi.json") + payload = json.loads(service_path.read_text(encoding="utf-8")) + + chat_operation = payload["paths"]["/chat-messages"]["post"] + assert chat_operation["summary"] == "Send Chat Message" + assert chat_operation["description"] == "Send a request to the chat application." + assert chat_operation["tags"] == ["Chatflows", "Chats"] + + rename_operation = payload["paths"]["/conversations/{c_id}/name"]["post"] + assert rename_operation["summary"] == "Rename Conversation" + + def test_standalone_inline_model_name_includes_list_constraints(): module = _load_generate_swagger_specs_module() diff --git a/api/tests/unit_tests/controllers/test_swagger.py b/api/tests/unit_tests/controllers/test_swagger.py index 0d17409270d..ebdc300a8c6 100644 --- a/api/tests/unit_tests/controllers/test_swagger.py +++ b/api/tests/unit_tests/controllers/test_swagger.py @@ -206,6 +206,31 @@ def test_service_document_file_routes_document_multipart_form_data(monkeypatch: assert update_operation["requestBody"]["required"] is False +def test_service_openapi_merges_public_api_reference_descriptions(monkeypatch: pytest.MonkeyPatch): + from configs import dify_config + from controllers.service_api import bp as service_api_bp + + monkeypatch.setattr(dify_config, "SWAGGER_UI_ENABLED", True) + + app = Flask(__name__) + app.config["TESTING"] = True + app.config["RESTX_INCLUDE_ALL_MODELS"] = True + app.register_blueprint(service_api_bp) + + payload = app.test_client().get("/v1/openapi.json").get_json() + + chat_operation = payload["paths"]["/chat-messages"]["post"] + assert chat_operation["summary"] == "Send Chat Message" + assert chat_operation["description"] == "Send a request to the chat application." + assert chat_operation["tags"] == ["Chats", "Chatflows"] + assert chat_operation["responses"]["200"]["description"].startswith("Successful response.") + + rename_operation = payload["paths"]["/conversations/{c_id}/name"]["post"] + assert rename_operation["summary"] == "Rename Conversation" + assert rename_operation["tags"] == ["Conversations"] + assert _parameters_by_name(rename_operation)["c_id"]["description"] == "Conversation ID" + + def test_service_document_list_documents_query_params_render(monkeypatch: pytest.MonkeyPatch): from configs import dify_config from controllers.service_api import bp as service_api_bp diff --git a/packages/contracts/generated/api/service/orpc.gen.ts b/packages/contracts/generated/api/service/orpc.gen.ts index ceb9dcbeb8a..b15cc78d07d 100644 --- a/packages/contracts/generated/api/service/orpc.gen.ts +++ b/packages/contracts/generated/api/service/orpc.gen.ts @@ -234,21 +234,20 @@ export const root = { } /** - * Get all feedbacks for the application + * List App Feedbacks * - * Get all feedbacks for the application - * Returns paginated list of all feedback submitted for messages in this app. + * Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback. */ export const get2 = oc .route({ description: - 'Get all feedbacks for the application\nReturns paginated list of all feedback submitted for messages in this app.', + 'Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.', inputStructure: 'detailed', method: 'GET', operationId: 'getAppFeedbacks', path: '/app/feedbacks', - summary: 'Get all feedbacks for the application', - tags: ['service_api'], + summary: 'List App Feedbacks', + tags: ['Feedback'], }) .input(z.object({ query: zGetAppFeedbacksQuery.optional() })) .output(zGetAppFeedbacksResponse) @@ -262,19 +261,20 @@ export const app = { } /** - * Get the status of an annotation reply action job + * Get Annotation Reply Job Status * - * Get the status of an annotation reply action job + * Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply). */ export const get3 = oc .route({ - description: 'Get the status of an annotation reply action job', + description: + 'Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).', inputStructure: 'detailed', method: 'GET', operationId: 'getAppsAnnotationReplyByActionStatusByJobId', path: '/apps/annotation-reply/{action}/status/{job_id}', - summary: 'Get the status of an annotation reply action job', - tags: ['service_api'], + summary: 'Get Annotation Reply Job Status', + tags: ['Annotations'], }) .input(z.object({ params: zGetAppsAnnotationReplyByActionStatusByJobIdPath })) .output(zGetAppsAnnotationReplyByActionStatusByJobIdResponse) @@ -288,19 +288,20 @@ export const status = { } /** - * Enable or disable annotation reply feature + * Configure Annotation Reply * - * Enable or disable annotation reply feature + * Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress. */ export const post = oc .route({ - description: 'Enable or disable annotation reply feature', + description: + 'Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.', inputStructure: 'detailed', method: 'POST', operationId: 'postAppsAnnotationReplyByAction', path: '/apps/annotation-reply/{action}', - summary: 'Enable or disable annotation reply feature', - tags: ['service_api'], + summary: 'Configure Annotation Reply', + tags: ['Annotations'], }) .input( z.object({ @@ -320,38 +321,38 @@ export const annotationReply = { } /** - * Delete an annotation + * Delete Annotation * - * Delete an annotation + * Deletes an annotation and its associated hit history. */ export const delete_ = oc .route({ - description: 'Delete an annotation', + description: 'Deletes an annotation and its associated hit history.', inputStructure: 'detailed', method: 'DELETE', operationId: 'deleteAppsAnnotationsByAnnotationId', path: '/apps/annotations/{annotation_id}', successStatus: 204, - summary: 'Delete an annotation', - tags: ['service_api'], + summary: 'Delete Annotation', + tags: ['Annotations'], }) .input(z.object({ params: zDeleteAppsAnnotationsByAnnotationIdPath })) .output(zDeleteAppsAnnotationsByAnnotationIdResponse) /** - * Update an existing annotation + * Update Annotation * - * Update an existing annotation + * Updates the question and answer of an existing annotation. */ export const put = oc .route({ - description: 'Update an existing annotation', + description: 'Updates the question and answer of an existing annotation.', inputStructure: 'detailed', method: 'PUT', operationId: 'putAppsAnnotationsByAnnotationId', path: '/apps/annotations/{annotation_id}', - summary: 'Update an existing annotation', - tags: ['service_api'], + summary: 'Update Annotation', + tags: ['Annotations'], }) .input( z.object({ @@ -367,38 +368,40 @@ export const byAnnotationId = { } /** - * List annotations for the application + * List Annotations * - * List annotations for the application + * Retrieves a paginated list of annotations for the application. Supports keyword search filtering. */ export const get4 = oc .route({ - description: 'List annotations for the application', + description: + 'Retrieves a paginated list of annotations for the application. Supports keyword search filtering.', inputStructure: 'detailed', method: 'GET', operationId: 'getAppsAnnotations', path: '/apps/annotations', - summary: 'List annotations for the application', - tags: ['service_api'], + summary: 'List Annotations', + tags: ['Annotations'], }) .input(z.object({ query: zGetAppsAnnotationsQuery.optional() })) .output(zGetAppsAnnotationsResponse) /** - * Create a new annotation + * Create Annotation * - * Create a new annotation + * Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response. */ export const post2 = oc .route({ - description: 'Create a new annotation', + description: + 'Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response.', inputStructure: 'detailed', method: 'POST', operationId: 'postAppsAnnotations', path: '/apps/annotations', successStatus: 201, - summary: 'Create a new annotation', - tags: ['service_api'], + summary: 'Create Annotation', + tags: ['Annotations'], }) .input(z.object({ body: zPostAppsAnnotationsBody })) .output(zPostAppsAnnotationsResponse) @@ -415,21 +418,20 @@ export const apps = { } /** - * Convert audio to text using speech-to-text + * Convert Audio to Text * - * Convert audio to text using speech-to-text - * Accepts an audio file upload and returns the transcribed text. + * Convert audio file to text. Supported MIME types: `audio/mp3`, `audio/mpga`, `audio/m4a`, `audio/wav`, and `audio/amr`. File size limit is `30 MB`. */ export const post3 = oc .route({ description: - 'Convert audio to text using speech-to-text\nAccepts an audio file upload and returns the transcribed text.', + 'Convert audio file to text. Supported MIME types: `audio/mp3`, `audio/mpga`, `audio/m4a`, `audio/wav`, and `audio/amr`. File size limit is `30 MB`.', inputStructure: 'detailed', method: 'POST', operationId: 'postAudioToText', path: '/audio-to-text', - summary: 'Convert audio to text using speech-to-text', - tags: ['service_api'], + summary: 'Convert Audio to Text', + tags: ['TTS'], }) .input(z.object({ body: zPostAudioToTextBody })) .output(zPostAudioToTextResponse) @@ -439,19 +441,19 @@ export const audioToText = { } /** - * Stop a running chat message generation + * Stop Chat Message Generation * - * Stop a running chat message generation + * Stops a chat message generation task. Only supported in `streaming` mode. */ export const post4 = oc .route({ - description: 'Stop a running chat message generation', + description: 'Stops a chat message generation task. Only supported in `streaming` mode.', inputStructure: 'detailed', method: 'POST', operationId: 'postChatMessagesByTaskIdStop', path: '/chat-messages/{task_id}/stop', - summary: 'Stop a running chat message generation', - tags: ['service_api'], + summary: 'Stop Chat Message Generation', + tags: ['Chatflows', 'Chats'], }) .input( z.object({ @@ -470,22 +472,19 @@ export const byTaskId = { } /** - * Send a message in a chat conversation + * Send Chat Message * - * Send a message in a chat conversation - * This endpoint handles chat messages for chat, agent chat, and advanced chat applications. - * Supports conversation management and both blocking and streaming response modes. + * Send a request to the chat application. */ export const post5 = oc .route({ - description: - 'Send a message in a chat conversation\nThis endpoint handles chat messages for chat, agent chat, and advanced chat applications.\nSupports conversation management and both blocking and streaming response modes.', + description: 'Send a request to the chat application.', inputStructure: 'detailed', method: 'POST', operationId: 'postChatMessages', path: '/chat-messages', - summary: 'Send a message in a chat conversation', - tags: ['service_api'], + summary: 'Send Chat Message', + tags: ['Chatflows', 'Chats'], }) .input(z.object({ body: zPostChatMessagesBody })) .output(zPostChatMessagesResponse) @@ -496,19 +495,19 @@ export const chatMessages = { } /** - * Stop a running completion task + * Stop Completion Message Generation * - * Stop a running completion task + * Stops a completion message generation task. Only supported in `streaming` mode. */ export const post6 = oc .route({ - description: 'Stop a running completion task', + description: 'Stops a completion message generation task. Only supported in `streaming` mode.', inputStructure: 'detailed', method: 'POST', operationId: 'postCompletionMessagesByTaskIdStop', path: '/completion-messages/{task_id}/stop', - summary: 'Stop a running completion task', - tags: ['service_api'], + summary: 'Stop Completion Message Generation', + tags: ['Completions'], }) .input( z.object({ @@ -527,22 +526,19 @@ export const byTaskId2 = { } /** - * Create a completion for the given prompt + * Send Completion Message * - * Create a completion for the given prompt - * This endpoint generates a completion based on the provided inputs and query. - * Supports both blocking and streaming response modes. + * Send a request to the text generation application. */ export const post7 = oc .route({ - description: - 'Create a completion for the given prompt\nThis endpoint generates a completion based on the provided inputs and query.\nSupports both blocking and streaming response modes.', + description: 'Send a request to the text generation application.', inputStructure: 'detailed', method: 'POST', operationId: 'postCompletionMessages', path: '/completion-messages', - summary: 'Create a completion for the given prompt', - tags: ['service_api'], + summary: 'Send Completion Message', + tags: ['Completions'], }) .input(z.object({ body: zPostCompletionMessagesBody })) .output(zPostCompletionMessagesResponse) @@ -553,19 +549,20 @@ export const completionMessages = { } /** - * Rename a conversation or auto-generate a name + * Rename Conversation * - * Rename a conversation or auto-generate a name + * Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations. */ export const post8 = oc .route({ - description: 'Rename a conversation or auto-generate a name', + description: + 'Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations.', inputStructure: 'detailed', method: 'POST', operationId: 'postConversationsByCIdName', path: '/conversations/{c_id}/name', - summary: 'Rename a conversation or auto-generate a name', - tags: ['service_api'], + summary: 'Rename Conversation', + tags: ['Conversations'], }) .input( z.object({ body: zPostConversationsByCIdNameBody, params: zPostConversationsByCIdNamePath }), @@ -577,22 +574,20 @@ export const name = { } /** - * Update a conversation variable's value + * Update Conversation Variable * - * Update a conversation variable's value - * Allows updating the value of a specific conversation variable. - * The value must match the variable's expected type. + * Update the value of a specific conversation variable. The value must match the expected type. */ export const put2 = oc .route({ description: - 'Update a conversation variable\'s value\nAllows updating the value of a specific conversation variable.\nThe value must match the variable\'s expected type.', + 'Update the value of a specific conversation variable. The value must match the expected type.', inputStructure: 'detailed', method: 'PUT', operationId: 'putConversationsByCIdVariablesByVariableId', path: '/conversations/{c_id}/variables/{variable_id}', - summary: 'Update a conversation variable\'s value', - tags: ['service_api'], + summary: 'Update Conversation Variable', + tags: ['Conversations'], }) .input( z.object({ @@ -607,21 +602,19 @@ export const byVariableId = { } /** - * List all variables for a conversation + * List Conversation Variables * - * List all variables for a conversation - * Conversational variables are only available for chat applications. + * Retrieve variables from a specific conversation. */ export const get5 = oc .route({ - description: - 'List all variables for a conversation\nConversational variables are only available for chat applications.', + description: 'Retrieve variables from a specific conversation.', inputStructure: 'detailed', method: 'GET', operationId: 'getConversationsByCIdVariables', path: '/conversations/{c_id}/variables', - summary: 'List all variables for a conversation', - tags: ['service_api'], + summary: 'List Conversation Variables', + tags: ['Conversations'], }) .input( z.object({ @@ -637,20 +630,20 @@ export const variables = { } /** - * Delete a specific conversation + * Delete Conversation * - * Delete a specific conversation + * Delete a conversation. */ export const delete2 = oc .route({ - description: 'Delete a specific conversation', + description: 'Delete a conversation.', inputStructure: 'detailed', method: 'DELETE', operationId: 'deleteConversationsByCId', path: '/conversations/{c_id}', successStatus: 204, - summary: 'Delete a specific conversation', - tags: ['service_api'], + summary: 'Delete Conversation', + tags: ['Conversations'], }) .input(z.object({ body: zDeleteConversationsByCIdBody, params: zDeleteConversationsByCIdPath })) .output(zDeleteConversationsByCIdResponse) @@ -662,21 +655,20 @@ export const byCId = { } /** - * List all conversations for the current user + * List Conversations * - * List all conversations for the current user - * Supports pagination using last_id and limit parameters. + * Retrieve the conversation list for the current user, ordered by most recently active. */ export const get6 = oc .route({ description: - 'List all conversations for the current user\nSupports pagination using last_id and limit parameters.', + 'Retrieve the conversation list for the current user, ordered by most recently active.', inputStructure: 'detailed', method: 'GET', operationId: 'getConversations', path: '/conversations', - summary: 'List all conversations for the current user', - tags: ['service_api'], + summary: 'List Conversations', + tags: ['Conversations'], }) .input(z.object({ query: zGetConversationsQuery.optional() })) .output(zGetConversationsResponse) @@ -687,22 +679,21 @@ export const conversations = { } /** - * Upload a file for use in conversations + * Upload Pipeline File * - * Upload a file to a knowledgebase pipeline - * Accepts a single file upload via multipart/form-data. + * Upload a file for use in a knowledge pipeline. Accepts a single file via `multipart/form-data`. */ export const post9 = oc .route({ description: - 'Upload a file to a knowledgebase pipeline\nAccepts a single file upload via multipart/form-data.', + 'Upload a file for use in a knowledge pipeline. Accepts a single file via `multipart/form-data`.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsPipelineFileUpload', path: '/datasets/pipeline/file-upload', successStatus: 201, - summary: 'Upload a file for use in conversations', - tags: ['service_api'], + summary: 'Upload Pipeline File', + tags: ['Knowledge Pipeline'], }) .input(z.object({ body: zPostDatasetsPipelineFileUploadBody })) .output(zPostDatasetsPipelineFileUploadResponse) @@ -716,17 +707,21 @@ export const pipeline = { } /** - * Bind tags to a dataset + * Create Tag Binding + * + * Bind one or more tags to a knowledge base. A knowledge base can have multiple tags. */ export const post10 = oc .route({ - description: 'Bind tags to a dataset', + description: + 'Bind one or more tags to a knowledge base. A knowledge base can have multiple tags.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsTagsBinding', path: '/datasets/tags/binding', successStatus: 204, - tags: ['service_api'], + summary: 'Create Tag Binding', + tags: ['Tags'], }) .input(z.object({ body: zPostDatasetsTagsBindingBody })) .output(zPostDatasetsTagsBindingResponse) @@ -736,17 +731,20 @@ export const binding = { } /** - * Unbind tags from a dataset + * Delete Tag Binding + * + * Remove one or more tags from a knowledge base. */ export const post11 = oc .route({ - description: 'Unbind tags from a dataset', + description: 'Remove one or more tags from a knowledge base.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsTagsUnbinding', path: '/datasets/tags/unbinding', successStatus: 204, - tags: ['service_api'], + summary: 'Delete Tag Binding', + tags: ['Tags'], }) .input(z.object({ body: zPostDatasetsTagsUnbindingBody })) .output(zPostDatasetsTagsUnbindingResponse) @@ -756,70 +754,74 @@ export const unbinding = { } /** - * Delete a knowledge type tag + * Delete Knowledge Tag * - * Delete a knowledge type tag + * Permanently delete a knowledge base tag. Does not delete the knowledge bases that were tagged. */ export const delete3 = oc .route({ - description: 'Delete a knowledge type tag', + description: + 'Permanently delete a knowledge base tag. Does not delete the knowledge bases that were tagged.', inputStructure: 'detailed', method: 'DELETE', operationId: 'deleteDatasetsTags', path: '/datasets/tags', successStatus: 204, - summary: 'Delete a knowledge type tag', - tags: ['service_api'], + summary: 'Delete Knowledge Tag', + tags: ['Tags'], }) .input(z.object({ body: zDeleteDatasetsTagsBody })) .output(zDeleteDatasetsTagsResponse) /** - * Get all knowledge type tags + * List Knowledge Tags * - * Get all knowledge type tags + * Returns the list of all knowledge base tags in the workspace. */ export const get7 = oc .route({ - description: 'Get all knowledge type tags', + description: 'Returns the list of all knowledge base tags in the workspace.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsTags', path: '/datasets/tags', - summary: 'Get all knowledge type tags', - tags: ['service_api'], + summary: 'List Knowledge Tags', + tags: ['Tags'], }) .output(zGetDatasetsTagsResponse) /** - * Update a knowledge type tag + * Update Knowledge Tag + * + * Rename an existing knowledge base tag. */ export const patch = oc .route({ - description: 'Update a knowledge type tag', + description: 'Rename an existing knowledge base tag.', inputStructure: 'detailed', method: 'PATCH', operationId: 'patchDatasetsTags', path: '/datasets/tags', - tags: ['service_api'], + summary: 'Update Knowledge Tag', + tags: ['Tags'], }) .input(z.object({ body: zPatchDatasetsTagsBody })) .output(zPatchDatasetsTagsResponse) /** - * Add a knowledge type tag + * Create Knowledge Tag * - * Add a knowledge type tag + * Create a new tag for organizing knowledge bases. */ export const post12 = oc .route({ - description: 'Add a knowledge type tag', + description: 'Create a new tag for organizing knowledge bases.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsTags', path: '/datasets/tags', - summary: 'Add a knowledge type tag', - tags: ['service_api'], + summary: 'Create Knowledge Tag', + tags: ['Tags'], }) .input(z.object({ body: zPostDatasetsTagsBody })) .output(zPostDatasetsTagsResponse) @@ -834,16 +836,20 @@ export const tags = { } /** - * Create a new document by uploading a file + * Create Document by File + * + * Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. */ export const post13 = oc .route({ - description: 'Create a new document by uploading a file', + description: + 'Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentCreateByFile', path: '/datasets/{dataset_id}/document/create-by-file', - tags: ['service_api'], + summary: 'Create Document by File', + tags: ['Documents'], }) .input( z.object({ @@ -854,19 +860,23 @@ export const post13 = oc .output(zPostDatasetsByDatasetIdDocumentCreateByFileResponse) /** - * Create a new document by uploading a file + * Create Document by File + * + * Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. * * @deprecated */ export const post14 = oc .route({ deprecated: true, - description: 'Create a new document by uploading a file', + description: + 'Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentCreateByFile', path: '/datasets/{dataset_id}/document/create_by_file', - tags: ['service_api'], + summary: 'Create Document by File', + tags: ['Documents'], }) .input( z.object({ @@ -881,16 +891,20 @@ export const createByFile = { } /** - * Create a new document by providing text content + * Create Document by Text + * + * Create a document from raw text content. The document is processed asynchronously — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. */ export const post15 = oc .route({ - description: 'Create a new document by providing text content', + description: + 'Create a document from raw text content. The document is processed asynchronously — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentCreateByText', path: '/datasets/{dataset_id}/document/create-by-text', - tags: ['service_api'], + summary: 'Create Document by Text', + tags: ['Documents'], }) .input( z.object({ @@ -934,16 +948,20 @@ export const document_ = { } /** - * Download selected uploaded documents as a single ZIP archive + * Download Documents as ZIP + * + * Download multiple uploaded-file documents as a single ZIP archive. Accepts up to `100` document IDs. */ export const post17 = oc .route({ - description: 'Download selected uploaded documents as a single ZIP archive', + description: + 'Download multiple uploaded-file documents as a single ZIP archive. Accepts up to `100` document IDs.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentsDownloadZip', path: '/datasets/{dataset_id}/documents/download-zip', - tags: ['service_api'], + summary: 'Download Documents as ZIP', + tags: ['Documents'], }) .input( z.object({ @@ -958,19 +976,20 @@ export const downloadZip = { } /** - * Update metadata for multiple documents + * Update Document Metadata in Batch * - * Update metadata for multiple documents + * Update metadata values for multiple documents at once. Each document in the request receives the specified metadata key-value pairs. */ export const post18 = oc .route({ - description: 'Update metadata for multiple documents', + description: + 'Update metadata values for multiple documents at once. Each document in the request receives the specified metadata key-value pairs.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentsMetadata', path: '/datasets/{dataset_id}/documents/metadata', - summary: 'Update metadata for multiple documents', - tags: ['service_api'], + summary: 'Update Document Metadata in Batch', + tags: ['Metadata'], }) .input( z.object({ @@ -985,33 +1004,19 @@ export const metadata = { } /** - * Batch update document status + * Update Document Status in Batch * - * Batch update document status - * Args: - * tenant_id: tenant id - * dataset_id: dataset id - * action: action to perform (Literal["enable", "disable", "archive", "un_archive"]) - * - * Returns: - * dict: A dictionary with a key 'result' and a value 'success' - * int: HTTP status code 200 indicating that the operation was successful. - * - * Raises: - * NotFound: If the dataset with the given ID does not exist. - * Forbidden: If the user does not have permission. - * InvalidActionError: If the action is invalid or cannot be performed. + * Enable, disable, archive, or unarchive multiple documents at once. */ export const patch2 = oc .route({ - description: - 'Batch update document status\nArgs:\n tenant_id: tenant id\n dataset_id: dataset id\n action: action to perform (Literal["enable", "disable", "archive", "un_archive"])\n\nReturns:\n dict: A dictionary with a key \'result\' and a value \'success\'\n int: HTTP status code 200 indicating that the operation was successful.\n\nRaises:\n NotFound: If the dataset with the given ID does not exist.\n Forbidden: If the user does not have permission.\n InvalidActionError: If the action is invalid or cannot be performed.', + description: 'Enable, disable, archive, or unarchive multiple documents at once.', inputStructure: 'detailed', method: 'PATCH', operationId: 'patchDatasetsByDatasetIdDocumentsStatusByAction', path: '/datasets/{dataset_id}/documents/status/{action}', - summary: 'Batch update document status', - tags: ['service_api'], + summary: 'Update Document Status in Batch', + tags: ['Documents'], }) .input( z.object({ @@ -1030,16 +1035,20 @@ export const status2 = { } /** - * Get indexing status for documents in a batch + * Get Document Indexing Status + * + * Check the indexing progress of documents in a batch. Returns the current processing stage and chunk completion counts for each document. Poll this endpoint until `indexing_status` reaches `completed` or `error`. The status progresses through: `waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`. */ export const get8 = oc .route({ - description: 'Get indexing status for documents in a batch', + description: + 'Check the indexing progress of documents in a batch. Returns the current processing stage and chunk completion counts for each document. Poll this endpoint until `indexing_status` reaches `completed` or `error`. The status progresses through: `waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdDocumentsByBatchIndexingStatus', path: '/datasets/{dataset_id}/documents/{batch}/indexing-status', - tags: ['service_api'], + summary: 'Get Document Indexing Status', + tags: ['Documents'], }) .input(z.object({ params: zGetDatasetsByDatasetIdDocumentsByBatchIndexingStatusPath })) .output(zGetDatasetsByDatasetIdDocumentsByBatchIndexingStatusResponse) @@ -1053,16 +1062,19 @@ export const byBatch = { } /** - * Get a signed download URL for a document's original uploaded file + * Download Document + * + * Get a signed download URL for a document's original uploaded file. */ export const get9 = oc .route({ - description: 'Get a signed download URL for a document\'s original uploaded file', + description: 'Get a signed download URL for a document\'s original uploaded file.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdDocumentsByDocumentIdDownload', path: '/datasets/{dataset_id}/documents/{document_id}/download', - tags: ['service_api'], + summary: 'Download Document', + tags: ['Documents'], }) .input(z.object({ params: zGetDatasetsByDatasetIdDocumentsByDocumentIdDownloadPath })) .output(zGetDatasetsByDatasetIdDocumentsByDocumentIdDownloadResponse) @@ -1072,18 +1084,21 @@ export const download = { } /** - * Delete a specific child chunk + * Delete Child Chunk + * + * Permanently delete a child chunk from its parent chunk. */ export const delete4 = oc .route({ - description: 'Delete a specific child chunk', + description: 'Permanently delete a child chunk from its parent chunk.', inputStructure: 'detailed', method: 'DELETE', operationId: 'deleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksByChildChunkId', path: '/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}', successStatus: 204, - tags: ['service_api'], + summary: 'Delete Child Chunk', + tags: ['Chunks'], }) .input( z.object({ @@ -1096,17 +1111,20 @@ export const delete4 = oc ) /** - * Update a specific child chunk + * Update Child Chunk + * + * Update the content of an existing child chunk. */ export const patch3 = oc .route({ - description: 'Update a specific child chunk', + description: 'Update the content of an existing child chunk.', inputStructure: 'detailed', method: 'PATCH', operationId: 'patchDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksByChildChunkId', path: '/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}', - tags: ['service_api'], + summary: 'Update Child Chunk', + tags: ['Chunks'], }) .input( z.object({ @@ -1125,16 +1143,19 @@ export const byChildChunkId = { } /** - * List child chunks for a segment + * List Child Chunks + * + * Returns a paginated list of child chunks under a specific parent chunk. */ export const get10 = oc .route({ - description: 'List child chunks for a segment', + description: 'Returns a paginated list of child chunks under a specific parent chunk.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunks', path: '/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks', - tags: ['service_api'], + summary: 'List Child Chunks', + tags: ['Chunks'], }) .input( z.object({ @@ -1146,16 +1167,19 @@ export const get10 = oc .output(zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksResponse) /** - * Create a new child chunk for a segment + * Create Child Chunk + * + * Create a child chunk under the specified segment. */ export const post19 = oc .route({ - description: 'Create a new child chunk for a segment', + description: 'Create a child chunk under the specified segment.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunks', path: '/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks', - tags: ['service_api'], + summary: 'Create Child Chunk', + tags: ['Chunks'], }) .input( z.object({ @@ -1172,17 +1196,20 @@ export const childChunks = { } /** - * Delete a specific segment + * Delete Chunk + * + * Permanently delete a chunk from the document. */ export const delete5 = oc .route({ - description: 'Delete a specific segment', + description: 'Permanently delete a chunk from the document.', inputStructure: 'detailed', method: 'DELETE', operationId: 'deleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentId', path: '/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}', successStatus: 204, - tags: ['service_api'], + summary: 'Delete Chunk', + tags: ['Chunks'], }) .input( z.object({ params: zDeleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdPath }), @@ -1190,31 +1217,39 @@ export const delete5 = oc .output(zDeleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdResponse) /** - * Get a specific segment by ID + * Get Chunk + * + * Retrieve detailed information about a specific chunk, including its content, keywords, and indexing status. */ export const get11 = oc .route({ - description: 'Get a specific segment by ID', + description: + 'Retrieve detailed information about a specific chunk, including its content, keywords, and indexing status.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentId', path: '/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}', - tags: ['service_api'], + summary: 'Get Chunk', + tags: ['Chunks'], }) .input(z.object({ params: zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdPath })) .output(zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdResponse) /** - * Update a specific segment + * Update Chunk + * + * Update a chunk's content, keywords, or answer. Re-triggers indexing for the modified chunk. */ export const post20 = oc .route({ - description: 'Update a specific segment', + description: + 'Update a chunk\'s content, keywords, or answer. Re-triggers indexing for the modified chunk.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentId', path: '/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}', - tags: ['service_api'], + summary: 'Update Chunk', + tags: ['Chunks'], }) .input( z.object({ @@ -1232,16 +1267,20 @@ export const bySegmentId = { } /** - * List segments in a document + * List Chunks + * + * Returns a paginated list of chunks within a document. Supports filtering by keyword and status. */ export const get12 = oc .route({ - description: 'List segments in a document', + description: + 'Returns a paginated list of chunks within a document. Supports filtering by keyword and status.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdDocumentsByDocumentIdSegments', path: '/datasets/{dataset_id}/documents/{document_id}/segments', - tags: ['service_api'], + summary: 'List Chunks', + tags: ['Chunks'], }) .input( z.object({ @@ -1252,16 +1291,20 @@ export const get12 = oc .output(zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsResponse) /** - * Create segments in a document + * Create Chunks + * + * Create one or more chunks within a document. Each chunk can include optional keywords and an answer field (for QA-mode documents). */ export const post21 = oc .route({ - description: 'Create segments in a document', + description: + 'Create one or more chunks within a document. Each chunk can include optional keywords and an answer field (for QA-mode documents).', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentsByDocumentIdSegments', path: '/datasets/{dataset_id}/documents/{document_id}/segments', - tags: ['service_api'], + summary: 'Create Chunks', + tags: ['Chunks'], }) .input( z.object({ @@ -1278,7 +1321,9 @@ export const segments = { } /** - * Deprecated legacy alias for updating an existing document by uploading a file. Use PATCH /datasets/{dataset_id}/documents/{document_id} instead. + * Update Document by File + * + * Update an existing document by uploading a new file. Re-triggers indexing — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. * * @deprecated */ @@ -1286,12 +1331,13 @@ export const post22 = oc .route({ deprecated: true, description: - 'Deprecated legacy alias for updating an existing document by uploading a file. Use PATCH /datasets/{dataset_id}/documents/{document_id} instead.', + 'Update an existing document by uploading a new file. Re-triggers indexing — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFile', path: '/datasets/{dataset_id}/documents/{document_id}/update-by-file', - tags: ['service_api'], + summary: 'Update Document by File', + tags: ['Documents'], }) .input( z.object({ @@ -1302,7 +1348,9 @@ export const post22 = oc .output(zPostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFileResponse) /** - * Deprecated legacy alias for updating an existing document by uploading a file. Use PATCH /datasets/{dataset_id}/documents/{document_id} instead. + * Update Document by File + * + * Update an existing document by uploading a new file. Re-triggers indexing — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. * * @deprecated */ @@ -1310,12 +1358,13 @@ export const post23 = oc .route({ deprecated: true, description: - 'Deprecated legacy alias for updating an existing document by uploading a file. Use PATCH /datasets/{dataset_id}/documents/{document_id} instead.', + 'Update an existing document by uploading a new file. Re-triggers indexing — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFile', path: '/datasets/{dataset_id}/documents/{document_id}/update_by_file', - tags: ['service_api'], + summary: 'Update Document by File', + tags: ['Documents'], }) .input( z.object({ @@ -1330,16 +1379,20 @@ export const updateByFile = { } /** - * Update an existing document by providing text content + * Update Document by Text + * + * Update an existing document's text content, name, or processing configuration. Re-triggers indexing if content changes — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress. */ export const post24 = oc .route({ - description: 'Update an existing document by providing text content', + description: + 'Update an existing document\'s text content, name, or processing configuration. Re-triggers indexing if content changes — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdDocumentsByDocumentIdUpdateByText', path: '/datasets/{dataset_id}/documents/{document_id}/update-by-text', - tags: ['service_api'], + summary: 'Update Document by Text', + tags: ['Documents'], }) .input( z.object({ @@ -1378,35 +1431,39 @@ export const updateByText = { } /** - * Delete document + * Delete Document * - * Delete a document + * Permanently delete a document and all its chunks from the knowledge base. */ export const delete6 = oc .route({ - description: 'Delete a document', + description: 'Permanently delete a document and all its chunks from the knowledge base.', inputStructure: 'detailed', method: 'DELETE', operationId: 'deleteDatasetsByDatasetIdDocumentsByDocumentId', path: '/datasets/{dataset_id}/documents/{document_id}', successStatus: 204, - summary: 'Delete document', - tags: ['service_api'], + summary: 'Delete Document', + tags: ['Documents'], }) .input(z.object({ params: zDeleteDatasetsByDatasetIdDocumentsByDocumentIdPath })) .output(zDeleteDatasetsByDatasetIdDocumentsByDocumentIdResponse) /** - * Get a specific document by ID + * Get Document + * + * Retrieve detailed information about a specific document, including its indexing status, metadata, and processing statistics. */ export const get13 = oc .route({ - description: 'Get a specific document by ID', + description: + 'Retrieve detailed information about a specific document, including its indexing status, metadata, and processing statistics.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdDocumentsByDocumentId', path: '/datasets/{dataset_id}/documents/{document_id}', - tags: ['service_api'], + summary: 'Get Document', + tags: ['Documents'], }) .input( z.object({ @@ -1447,16 +1504,20 @@ export const byDocumentId = { } /** - * List all documents in a dataset + * List Documents + * + * Returns a paginated list of documents in the knowledge base. Supports filtering by keyword and indexing status. */ export const get14 = oc .route({ - description: 'List all documents in a dataset', + description: + 'Returns a paginated list of documents in the knowledge base. Supports filtering by keyword and indexing status.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdDocuments', path: '/datasets/{dataset_id}/documents', - tags: ['service_api'], + summary: 'List Documents', + tags: ['Documents'], }) .input( z.object({ @@ -1476,21 +1537,20 @@ export const documents = { } /** - * Perform hit testing on a dataset + * Retrieve Chunks from a Knowledge Base / Test Retrieval * - * Perform hit testing on a dataset - * Tests retrieval performance for the specified dataset. + * Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used for both production retrieval and test retrieval. */ export const post26 = oc .route({ description: - 'Perform hit testing on a dataset\nTests retrieval performance for the specified dataset.', + 'Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used for both production retrieval and test retrieval.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdHitTesting', path: '/datasets/{dataset_id}/hit-testing', - summary: 'Perform hit testing on a dataset', - tags: ['service_api'], + summary: 'Retrieve Chunks from a Knowledge Base / Test Retrieval', + tags: ['Knowledge Bases'], }) .input( z.object({ @@ -1505,19 +1565,19 @@ export const hitTesting = { } /** - * Enable or disable built-in metadata field + * Update Built-in Metadata Field * - * Enable or disable built-in metadata field + * Enable or disable built-in metadata fields for the knowledge base. */ export const post27 = oc .route({ - description: 'Enable or disable built-in metadata field', + description: 'Enable or disable built-in metadata fields for the knowledge base.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdMetadataBuiltInByAction', path: '/datasets/{dataset_id}/metadata/built-in/{action}', - summary: 'Enable or disable built-in metadata field', - tags: ['service_api'], + summary: 'Update Built-in Metadata Field', + tags: ['Metadata'], }) .input(z.object({ params: zPostDatasetsByDatasetIdMetadataBuiltInByActionPath })) .output(zPostDatasetsByDatasetIdMetadataBuiltInByActionResponse) @@ -1527,19 +1587,20 @@ export const byAction3 = { } /** - * Get all built-in metadata fields + * Get Built-in Metadata Fields * - * Get all built-in metadata fields + * Returns the list of built-in metadata fields provided by the system (e.g., document type, source URL). */ export const get15 = oc .route({ - description: 'Get all built-in metadata fields', + description: + 'Returns the list of built-in metadata fields provided by the system (e.g., document type, source URL).', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdMetadataBuiltIn', path: '/datasets/{dataset_id}/metadata/built-in', - summary: 'Get all built-in metadata fields', - tags: ['service_api'], + summary: 'Get Built-in Metadata Fields', + tags: ['Metadata'], }) .input(z.object({ params: zGetDatasetsByDatasetIdMetadataBuiltInPath })) .output(zGetDatasetsByDatasetIdMetadataBuiltInResponse) @@ -1550,38 +1611,39 @@ export const builtIn = { } /** - * Delete metadata + * Delete Metadata Field * - * Delete metadata + * Permanently delete a custom metadata field. Documents using this field will lose their metadata values for it. */ export const delete7 = oc .route({ - description: 'Delete metadata', + description: + 'Permanently delete a custom metadata field. Documents using this field will lose their metadata values for it.', inputStructure: 'detailed', method: 'DELETE', operationId: 'deleteDatasetsByDatasetIdMetadataByMetadataId', path: '/datasets/{dataset_id}/metadata/{metadata_id}', successStatus: 204, - summary: 'Delete metadata', - tags: ['service_api'], + summary: 'Delete Metadata Field', + tags: ['Metadata'], }) .input(z.object({ params: zDeleteDatasetsByDatasetIdMetadataByMetadataIdPath })) .output(zDeleteDatasetsByDatasetIdMetadataByMetadataIdResponse) /** - * Update metadata name + * Update Metadata Field * - * Update metadata name + * Rename a custom metadata field. */ export const patch5 = oc .route({ - description: 'Update metadata name', + description: 'Rename a custom metadata field.', inputStructure: 'detailed', method: 'PATCH', operationId: 'patchDatasetsByDatasetIdMetadataByMetadataId', path: '/datasets/{dataset_id}/metadata/{metadata_id}', - summary: 'Update metadata name', - tags: ['service_api'], + summary: 'Update Metadata Field', + tags: ['Metadata'], }) .input( z.object({ @@ -1597,38 +1659,40 @@ export const byMetadataId = { } /** - * Get all metadata for a dataset + * List Metadata Fields * - * Get all metadata for a dataset + * Returns the list of all metadata fields (both custom and built-in) for the knowledge base, along with the count of documents using each field. */ export const get16 = oc .route({ - description: 'Get all metadata for a dataset', + description: + 'Returns the list of all metadata fields (both custom and built-in) for the knowledge base, along with the count of documents using each field.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdMetadata', path: '/datasets/{dataset_id}/metadata', - summary: 'Get all metadata for a dataset', - tags: ['service_api'], + summary: 'List Metadata Fields', + tags: ['Metadata'], }) .input(z.object({ params: zGetDatasetsByDatasetIdMetadataPath })) .output(zGetDatasetsByDatasetIdMetadataResponse) /** - * Create metadata for a dataset + * Create Metadata Field * - * Create metadata for a dataset + * Create a custom metadata field for the knowledge base. Metadata fields can be used to annotate documents with structured information. */ export const post28 = oc .route({ - description: 'Create metadata for a dataset', + description: + 'Create a custom metadata field for the knowledge base. Metadata fields can be used to annotate documents with structured information.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdMetadata', path: '/datasets/{dataset_id}/metadata', successStatus: 201, - summary: 'Create metadata for a dataset', - tags: ['service_api'], + summary: 'Create Metadata Field', + tags: ['Metadata'], }) .input( z.object({ @@ -1646,19 +1710,20 @@ export const metadata2 = { } /** - * Resource for getting datasource plugins + * List Datasource Plugins * - * List all datasource plugins for a rag pipeline + * List the datasource nodes configured in the knowledge pipeline. Each node includes the plugin it uses plus the metadata needed to run it. */ export const get17 = oc .route({ - description: 'List all datasource plugins for a rag pipeline', + description: + 'List the datasource nodes configured in the knowledge pipeline. Each node includes the plugin it uses plus the metadata needed to run it.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdPipelineDatasourcePlugins', path: '/datasets/{dataset_id}/pipeline/datasource-plugins', - summary: 'Resource for getting datasource plugins', - tags: ['service_api'], + summary: 'List Datasource Plugins', + tags: ['Knowledge Pipeline'], }) .input( z.object({ @@ -1673,19 +1738,20 @@ export const datasourcePlugins = { } /** - * Resource for getting datasource plugins + * Run Datasource Node * - * Run a datasource node for a rag pipeline + * Execute a single datasource node within the knowledge pipeline. Returns a streaming response with the node execution results. */ export const post29 = oc .route({ - description: 'Run a datasource node for a rag pipeline', + description: + 'Execute a single datasource node within the knowledge pipeline. Returns a streaming response with the node execution results.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdPipelineDatasourceNodesByNodeIdRun', path: '/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run', - summary: 'Resource for getting datasource plugins', - tags: ['service_api'], + summary: 'Run Datasource Node', + tags: ['Knowledge Pipeline'], }) .input( z.object({ @@ -1712,19 +1778,20 @@ export const datasource = { } /** - * Resource for running a rag pipeline + * Run Pipeline * - * Run a datasource node for a rag pipeline + * Execute the full knowledge pipeline for a knowledge base. Supports both streaming and blocking response modes. */ export const post30 = oc .route({ - description: 'Run a datasource node for a rag pipeline', + description: + 'Execute the full knowledge pipeline for a knowledge base. Supports both streaming and blocking response modes.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdPipelineRun', path: '/datasets/{dataset_id}/pipeline/run', - summary: 'Resource for running a rag pipeline', - tags: ['service_api'], + summary: 'Run Pipeline', + tags: ['Knowledge Pipeline'], }) .input( z.object({ @@ -1745,21 +1812,20 @@ export const pipeline2 = { } /** - * Perform hit testing on a dataset + * Retrieve Chunks from a Knowledge Base / Test Retrieval * - * Perform hit testing on a dataset - * Tests retrieval performance for the specified dataset. + * Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used for both production retrieval and test retrieval. */ export const post31 = oc .route({ description: - 'Perform hit testing on a dataset\nTests retrieval performance for the specified dataset.', + 'Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used for both production retrieval and test retrieval.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasetsByDatasetIdRetrieve', path: '/datasets/{dataset_id}/retrieve', - summary: 'Perform hit testing on a dataset', - tags: ['service_api'], + summary: 'Retrieve Chunks from a Knowledge Base / Test Retrieval', + tags: ['Knowledge Bases'], }) .input( z.object({ @@ -1774,19 +1840,19 @@ export const retrieve = { } /** - * Get all knowledge type tags + * Get Knowledge Base Tags * - * Get tags bound to a specific dataset + * Returns the list of tags bound to a specific knowledge base. */ export const get18 = oc .route({ - description: 'Get tags bound to a specific dataset', + description: 'Returns the list of tags bound to a specific knowledge base.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetIdTags', path: '/datasets/{dataset_id}/tags', - summary: 'Get all knowledge type tags', - tags: ['service_api'], + summary: 'Get Knowledge Base Tags', + tags: ['Tags'], }) .input(z.object({ params: zGetDatasetsByDatasetIdTagsPath })) .output(zGetDatasetsByDatasetIdTagsResponse) @@ -1796,62 +1862,59 @@ export const tags2 = { } /** - * Deletes a dataset given its ID + * Delete Knowledge Base * - * Delete a dataset - * Args: - * _: ignore - * dataset_id (UUID): The ID of the dataset to be deleted. - * - * Returns: - * dict: A dictionary with a key 'result' and a value 'success' - * if the dataset was successfully deleted. Omitted in HTTP response. - * int: HTTP status code 204 indicating that the operation was successful. - * - * Raises: - * NotFound: If the dataset with the given ID does not exist. + * Permanently delete a knowledge base and all its documents. The knowledge base must not be in use by any application. */ export const delete8 = oc .route({ description: - 'Delete a dataset\nArgs:\n _: ignore\n dataset_id (UUID): The ID of the dataset to be deleted.\n\nReturns:\n dict: A dictionary with a key \'result\' and a value \'success\'\n if the dataset was successfully deleted. Omitted in HTTP response.\n int: HTTP status code 204 indicating that the operation was successful.\n\nRaises:\n NotFound: If the dataset with the given ID does not exist.', + 'Permanently delete a knowledge base and all its documents. The knowledge base must not be in use by any application.', inputStructure: 'detailed', method: 'DELETE', operationId: 'deleteDatasetsByDatasetId', path: '/datasets/{dataset_id}', successStatus: 204, - summary: 'Deletes a dataset given its ID', - tags: ['service_api'], + summary: 'Delete Knowledge Base', + tags: ['Knowledge Bases'], }) .input(z.object({ params: zDeleteDatasetsByDatasetIdPath })) .output(zDeleteDatasetsByDatasetIdResponse) /** - * Get a specific dataset by ID + * Get Knowledge Base + * + * Retrieve detailed information about a specific knowledge base, including its embedding model, retrieval configuration, and document statistics. */ export const get19 = oc .route({ - description: 'Get a specific dataset by ID', + description: + 'Retrieve detailed information about a specific knowledge base, including its embedding model, retrieval configuration, and document statistics.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasetsByDatasetId', path: '/datasets/{dataset_id}', - tags: ['service_api'], + summary: 'Get Knowledge Base', + tags: ['Knowledge Bases'], }) .input(z.object({ params: zGetDatasetsByDatasetIdPath })) .output(zGetDatasetsByDatasetIdResponse) /** - * Update an existing dataset + * Update Knowledge Base + * + * Update the name, description, permissions, or retrieval settings of an existing knowledge base. Only the fields provided in the request body are updated. */ export const patch6 = oc .route({ - description: 'Update an existing dataset', + description: + 'Update the name, description, permissions, or retrieval settings of an existing knowledge base. Only the fields provided in the request body are updated.', inputStructure: 'detailed', method: 'PATCH', operationId: 'patchDatasetsByDatasetId', path: '/datasets/{dataset_id}', - tags: ['service_api'], + summary: 'Update Knowledge Base', + tags: ['Knowledge Bases'], }) .input(z.object({ body: zPatchDatasetsByDatasetIdBody, params: zPatchDatasetsByDatasetIdPath })) .output(zPatchDatasetsByDatasetIdResponse) @@ -1870,37 +1933,39 @@ export const byDatasetId = { } /** - * Resource for getting datasets + * List Knowledge Bases * - * List all datasets + * Returns a paginated list of knowledge bases. Supports filtering by keyword and tags. */ export const get20 = oc .route({ - description: 'List all datasets', + description: + 'Returns a paginated list of knowledge bases. Supports filtering by keyword and tags.', inputStructure: 'detailed', method: 'GET', operationId: 'getDatasets', path: '/datasets', - summary: 'Resource for getting datasets', - tags: ['service_api'], + summary: 'List Knowledge Bases', + tags: ['Knowledge Bases'], }) .input(z.object({ query: zGetDatasetsQuery.optional() })) .output(zGetDatasetsResponse) /** - * Resource for creating datasets + * Create an Empty Knowledge Base * - * Create a new dataset + * Create a new empty knowledge base. After creation, use [Create Document by Text](/api-reference/documents/create-document-by-text) or [Create Document by File](/api-reference/documents/create-document-by-file) to add documents. */ export const post32 = oc .route({ - description: 'Create a new dataset', + description: + 'Create a new empty knowledge base. After creation, use [Create Document by Text](/api-reference/documents/create-document-by-text) or [Create Document by File](/api-reference/documents/create-document-by-file) to add documents.', inputStructure: 'detailed', method: 'POST', operationId: 'postDatasets', path: '/datasets', - summary: 'Resource for creating datasets', - tags: ['service_api'], + summary: 'Create an Empty Knowledge Base', + tags: ['Knowledge Bases'], }) .input(z.object({ body: zPostDatasetsBody })) .output(zPostDatasetsResponse) @@ -1914,22 +1979,20 @@ export const datasets = { } /** - * Get end user detail + * Get End User Info * - * Get an end user by ID - * This endpoint is scoped to the current app token's tenant/app to prevent - * cross-tenant/app access when an end-user ID is known. + * Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)). */ export const get21 = oc .route({ description: - 'Get an end user by ID\nThis endpoint is scoped to the current app token\'s tenant/app to prevent\ncross-tenant/app access when an end-user ID is known.', + 'Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).', inputStructure: 'detailed', method: 'GET', operationId: 'getEndUsersByEndUserId', path: '/end-users/{end_user_id}', - summary: 'Get end user detail', - tags: ['service_api'], + summary: 'Get End User Info', + tags: ['End Users'], }) .input(z.object({ params: zGetEndUsersByEndUserIdPath })) .output(zGetEndUsersByEndUserIdResponse) @@ -1943,22 +2006,21 @@ export const endUsers = { } /** - * Upload a file for use in conversations + * Upload File * - * Upload a file for use in conversations - * Accepts a single file upload via multipart/form-data. + * Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only. */ export const post33 = oc .route({ description: - 'Upload a file for use in conversations\nAccepts a single file upload via multipart/form-data.', + 'Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.', inputStructure: 'detailed', method: 'POST', operationId: 'postFilesUpload', path: '/files/upload', successStatus: 201, - summary: 'Upload a file for use in conversations', - tags: ['service_api'], + summary: 'Upload File', + tags: ['Files'], }) .input(z.object({ body: zPostFilesUploadBody })) .output(zPostFilesUploadResponse) @@ -1968,22 +2030,20 @@ export const upload = { } /** - * Preview/Download a file that was uploaded via Service API + * Download File * - * Preview or download a file uploaded via Service API - * Provides secure file preview/download functionality. - * Files can only be accessed if they belong to messages within the requesting app's context. + * Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application. */ export const get22 = oc .route({ description: - 'Preview or download a file uploaded via Service API\nProvides secure file preview/download functionality.\nFiles can only be accessed if they belong to messages within the requesting app\'s context.', + 'Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.', inputStructure: 'detailed', method: 'GET', operationId: 'getFilesByFileIdPreview', path: '/files/{file_id}/preview', - summary: 'Preview/Download a file that was uploaded via Service API', - tags: ['service_api'], + summary: 'Download File', + tags: ['Files'], }) .input( z.object({ @@ -2007,31 +2067,39 @@ export const files = { } /** - * Get a paused human input form by token + * Get Human Input Form + * + * Retrieve a paused Human Input form's contents using the `form_token` from a `human_input_required` event. Requires **WebApp** delivery. */ export const get23 = oc .route({ - description: 'Get a paused human input form by token', + description: + 'Retrieve a paused Human Input form\'s contents using the `form_token` from a `human_input_required` event. Requires **WebApp** delivery.', inputStructure: 'detailed', method: 'GET', operationId: 'getFormHumanInputByFormToken', path: '/form/human_input/{form_token}', - tags: ['service_api'], + summary: 'Get Human Input Form', + tags: ['Human Input'], }) .input(z.object({ params: zGetFormHumanInputByFormTokenPath })) .output(zGetFormHumanInputByFormTokenResponse) /** - * Submit a paused human input form by token + * Submit Human Input Form + * + * Submit the recipient's response to a paused Human Input form. The workflow resumes on acceptance; use [Stream Workflow Events](/api-reference/chatflows/stream-workflow-events) to follow subsequent events. Requires **WebApp** delivery. */ export const post34 = oc .route({ - description: 'Submit a paused human input form by token', + description: + 'Submit the recipient\'s response to a paused Human Input form. The workflow resumes on acceptance; use [Stream Workflow Events](/api-reference/chatflows/stream-workflow-events) to follow subsequent events. Requires **WebApp** delivery.', inputStructure: 'detailed', method: 'POST', operationId: 'postFormHumanInputByFormToken', path: '/form/human_input/{form_token}', - tags: ['service_api'], + summary: 'Submit Human Input Form', + tags: ['Human Input'], }) .input( z.object({ @@ -2055,21 +2123,20 @@ export const form = { } /** - * Get app information + * Get App Info * - * Get basic application information - * Returns basic information about the application including name, description, tags, and mode. + * Retrieve basic information about this application, including name, description, tags, and mode. */ export const get24 = oc .route({ description: - 'Get basic application information\nReturns basic information about the application including name, description, tags, and mode.', + 'Retrieve basic information about this application, including name, description, tags, and mode.', inputStructure: 'detailed', method: 'GET', operationId: 'getInfo', path: '/info', - summary: 'Get app information', - tags: ['service_api'], + summary: 'Get App Info', + tags: ['Applications'], }) .output(zGetInfoResponse) @@ -2078,21 +2145,20 @@ export const info = { } /** - * Submit feedback for a message + * Submit Message Feedback * - * Submit feedback for a message - * Allows users to rate messages as like/dislike and provide optional feedback content. + * Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback. */ export const post35 = oc .route({ description: - 'Submit feedback for a message\nAllows users to rate messages as like/dislike and provide optional feedback content.', + 'Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.', inputStructure: 'detailed', method: 'POST', operationId: 'postMessagesByMessageIdFeedbacks', path: '/messages/{message_id}/feedbacks', - summary: 'Submit feedback for a message', - tags: ['service_api'], + summary: 'Submit Message Feedback', + tags: ['Feedback'], }) .input( z.object({ @@ -2107,21 +2173,19 @@ export const feedbacks2 = { } /** - * Get suggested follow-up questions for a message + * Get Next Suggested Questions * - * Get suggested follow-up questions for a message - * Returns AI-generated follow-up questions based on the message content. + * Get next questions suggestions for the current message. */ export const get25 = oc .route({ - description: - 'Get suggested follow-up questions for a message\nReturns AI-generated follow-up questions based on the message content.', + description: 'Get next questions suggestions for the current message.', inputStructure: 'detailed', method: 'GET', operationId: 'getMessagesByMessageIdSuggested', path: '/messages/{message_id}/suggested', - summary: 'Get suggested follow-up questions for a message', - tags: ['service_api'], + summary: 'Get Next Suggested Questions', + tags: ['Chatflows', 'Chats'], }) .input( z.object({ @@ -2141,21 +2205,20 @@ export const byMessageId = { } /** - * List messages in a conversation + * List Conversation Messages * - * List messages in a conversation - * Retrieves messages with pagination support using first_id. + * Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order. */ export const get26 = oc .route({ description: - 'List messages in a conversation\nRetrieves messages with pagination support using first_id.', + 'Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order.', inputStructure: 'detailed', method: 'GET', operationId: 'getMessages', path: '/messages', - summary: 'List messages in a conversation', - tags: ['service_api'], + summary: 'List Conversation Messages', + tags: ['Conversations'], }) .input(z.object({ query: zGetMessagesQuery })) .output(zGetMessagesResponse) @@ -2166,21 +2229,20 @@ export const messages = { } /** - * Get app metadata + * Get App Meta * - * Get application metadata - * Returns metadata about the application including configuration and settings. + * Retrieve metadata about this application, including tool icons and other configuration details. */ export const get27 = oc .route({ description: - 'Get application metadata\nReturns metadata about the application including configuration and settings.', + 'Retrieve metadata about this application, including tool icons and other configuration details.', inputStructure: 'detailed', method: 'GET', operationId: 'getMeta', path: '/meta', - summary: 'Get app metadata', - tags: ['service_api'], + summary: 'Get App Meta', + tags: ['Applications'], }) .output(zGetMetaResponse) @@ -2189,21 +2251,20 @@ export const meta = { } /** - * Retrieve app parameters + * Get App Parameters * - * Retrieve application input parameters and configuration - * Returns the input form parameters and configuration for the application. + * Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values. */ export const get28 = oc .route({ description: - 'Retrieve application input parameters and configuration\nReturns the input form parameters and configuration for the application.', + 'Retrieve the application\'s input form configuration, including feature switches, input parameter names, types, and default values.', inputStructure: 'detailed', method: 'GET', operationId: 'getParameters', path: '/parameters', - summary: 'Retrieve app parameters', - tags: ['service_api'], + summary: 'Get App Parameters', + tags: ['Applications'], }) .output(zGetParametersResponse) @@ -2212,21 +2273,20 @@ export const parameters = { } /** - * Retrieve app site info + * Get App WebApp Settings * - * Get application site configuration - * Returns the site configuration for the application including theme, icons, and text. + * Retrieve the WebApp settings of this application, including site configuration, theme, and customization options. */ export const get29 = oc .route({ description: - 'Get application site configuration\nReturns the site configuration for the application including theme, icons, and text.', + 'Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.', inputStructure: 'detailed', method: 'GET', operationId: 'getSite', path: '/site', - summary: 'Retrieve app site info', - tags: ['service_api'], + summary: 'Get App WebApp Settings', + tags: ['Applications'], }) .output(zGetSiteResponse) @@ -2235,21 +2295,19 @@ export const site = { } /** - * Convert text to audio using text-to-speech + * Convert Text to Audio * - * Convert text to audio using text-to-speech - * Converts the provided text to audio using the specified voice. + * Convert text to speech. */ export const post36 = oc .route({ - description: - 'Convert text to audio using text-to-speech\nConverts the provided text to audio using the specified voice.', + description: 'Convert text to speech.', inputStructure: 'detailed', method: 'POST', operationId: 'postTextToAudio', path: '/text-to-audio', - summary: 'Convert text to audio using text-to-speech', - tags: ['service_api'], + summary: 'Convert Text to Audio', + tags: ['TTS'], }) .input(z.object({ body: zPostTextToAudioBody })) .output(zPostTextToAudioResponse) @@ -2259,16 +2317,20 @@ export const textToAudio = { } /** - * Get workflow execution events stream after resume + * Stream Workflow Events + * + * Resume 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. */ export const get30 = oc .route({ - description: 'Get workflow execution events stream after resume', + description: + 'Resume 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.', inputStructure: 'detailed', method: 'GET', operationId: 'getWorkflowByTaskIdEvents', path: '/workflow/{task_id}/events', - tags: ['service_api'], + summary: 'Stream Workflow Events', + tags: ['Chatflows', 'Workflows'], }) .input( z.object({ params: zGetWorkflowByTaskIdEventsPath, query: zGetWorkflowByTaskIdEventsQuery }), @@ -2288,21 +2350,19 @@ export const workflow = { } /** - * Get workflow app logs + * List Workflow Logs * - * Get workflow execution logs - * Returns paginated workflow execution logs with filtering options. + * Retrieve paginated workflow execution logs with filtering options. */ export const get31 = oc .route({ - description: - 'Get workflow execution logs\nReturns paginated workflow execution logs with filtering options.', + description: 'Retrieve paginated workflow execution logs with filtering options.', inputStructure: 'detailed', method: 'GET', operationId: 'getWorkflowsLogs', path: '/workflows/logs', - summary: 'Get workflow app logs', - tags: ['service_api'], + summary: 'List Workflow Logs', + tags: ['Chatflows', 'Workflows'], }) .input(z.object({ query: zGetWorkflowsLogsQuery.optional() })) .output(zGetWorkflowsLogsResponse) @@ -2312,21 +2372,20 @@ export const logs = { } /** - * Get a workflow task running detail + * Get Workflow Run Detail * - * Get workflow run details - * Returns detailed information about a specific workflow run. + * Retrieve the current execution results of a workflow task based on the workflow execution ID. */ export const get32 = oc .route({ description: - 'Get workflow run details\nReturns detailed information about a specific workflow run.', + 'Retrieve the current execution results of a workflow task based on the workflow execution ID.', inputStructure: 'detailed', method: 'GET', operationId: 'getWorkflowsRunByWorkflowRunId', path: '/workflows/run/{workflow_run_id}', - summary: 'Get a workflow task running detail', - tags: ['service_api'], + summary: 'Get Workflow Run Detail', + tags: ['Chatflows', 'Workflows'], }) .input(z.object({ params: zGetWorkflowsRunByWorkflowRunIdPath })) .output(zGetWorkflowsRunByWorkflowRunIdResponse) @@ -2336,22 +2395,19 @@ export const byWorkflowRunId = { } /** - * Execute a workflow + * Run Workflow * - * Execute a workflow - * Runs a workflow with the provided inputs and returns the results. - * Supports both blocking and streaming response modes. + * Execute a workflow. Cannot be executed without a published workflow. */ export const post37 = oc .route({ - description: - 'Execute a workflow\nRuns a workflow with the provided inputs and returns the results.\nSupports both blocking and streaming response modes.', + description: 'Execute a workflow. Cannot be executed without a published workflow.', inputStructure: 'detailed', method: 'POST', operationId: 'postWorkflowsRun', path: '/workflows/run', - summary: 'Execute a workflow', - tags: ['service_api'], + summary: 'Run Workflow', + tags: ['Workflows'], }) .input(z.object({ body: zPostWorkflowsRunBody })) .output(zPostWorkflowsRunResponse) @@ -2362,19 +2418,19 @@ export const run3 = { } /** - * Stop a running workflow task + * Stop Workflow Task * - * Stop a running workflow task + * Stop a running workflow task. Only supported in `streaming` mode. */ export const post38 = oc .route({ - description: 'Stop a running workflow task', + description: 'Stop a running workflow task. Only supported in `streaming` mode.', inputStructure: 'detailed', method: 'POST', operationId: 'postWorkflowsTasksByTaskIdStop', path: '/workflows/tasks/{task_id}/stop', - summary: 'Stop a running workflow task', - tags: ['service_api'], + summary: 'Stop Workflow Task', + tags: ['Workflows'], }) .input( z.object({ @@ -2397,21 +2453,20 @@ export const tasks = { } /** - * Run specific workflow by ID + * Run Workflow by ID * - * Execute a specific workflow by ID - * Executes a specific workflow version identified by its ID. + * Execute a specific workflow version identified by its ID. Useful for running a particular published version of the workflow. */ export const post39 = oc .route({ description: - 'Execute a specific workflow by ID\nExecutes a specific workflow version identified by its ID.', + 'Execute a specific workflow version identified by its ID. Useful for running a particular published version of the workflow.', inputStructure: 'detailed', method: 'POST', operationId: 'postWorkflowsByWorkflowIdRun', path: '/workflows/{workflow_id}/run', - summary: 'Run specific workflow by ID', - tags: ['service_api'], + summary: 'Run Workflow by ID', + tags: ['Workflows'], }) .input( z.object({ @@ -2437,21 +2492,20 @@ export const workflows = { } /** - * Get available models by model type + * Get Available Models * - * Get available models by model type - * Returns a list of available models for the specified model type. + * Retrieve the list of available models by type. Primarily used to query `text-embedding` and `rerank` models for knowledge base configuration. */ export const get33 = oc .route({ description: - 'Get available models by model type\nReturns a list of available models for the specified model type.', + 'Retrieve the list of available models by type. Primarily used to query `text-embedding` and `rerank` models for knowledge base configuration.', inputStructure: 'detailed', method: 'GET', operationId: 'getWorkspacesCurrentModelsModelTypesByModelType', path: '/workspaces/current/models/model-types/{model_type}', - summary: 'Get available models by model type', - tags: ['service_api'], + summary: 'Get Available Models', + tags: ['Models'], }) .input(z.object({ params: zGetWorkspacesCurrentModelsModelTypesByModelTypePath })) .output(zGetWorkspacesCurrentModelsModelTypesByModelTypeResponse) diff --git a/packages/contracts/generated/api/service/types.gen.ts b/packages/contracts/generated/api/service/types.gen.ts index 4ee8dcf4933..75d6a4b5a97 100644 --- a/packages/contracts/generated/api/service/types.gen.ts +++ b/packages/contracts/generated/api/service/types.gen.ts @@ -1712,6 +1712,7 @@ export type GetAppsAnnotationReplyByActionStatusByJobIdData = { } export type GetAppsAnnotationReplyByActionStatusByJobIdErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -1867,6 +1868,7 @@ export type PostChatMessagesByTaskIdStopData = { } export type PostChatMessagesByTaskIdStopErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -1891,6 +1893,7 @@ export type PostCompletionMessagesErrors = { 401: unknown 403: unknown 404: unknown + 429: unknown 500: unknown } @@ -1911,6 +1914,7 @@ export type PostCompletionMessagesByTaskIdStopData = { } export type PostCompletionMessagesByTaskIdStopErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -1936,6 +1940,7 @@ export type GetConversationsData = { } export type GetConversationsErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -1957,6 +1962,7 @@ export type DeleteConversationsByCIdData = { } export type DeleteConversationsByCIdErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -1979,6 +1985,7 @@ export type PostConversationsByCIdNameData = { } export type PostConversationsByCIdNameErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2006,6 +2013,7 @@ export type GetConversationsByCIdVariablesData = { } export type GetConversationsByCIdVariablesErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2077,6 +2085,7 @@ export type PostDatasetsErrors = { 400: unknown 401: unknown 403: unknown + 409: unknown } export type PostDatasetsResponses = { @@ -2513,6 +2522,7 @@ export type DeleteDatasetsByDatasetIdDocumentsByDocumentIdData = { } export type DeleteDatasetsByDatasetIdDocumentsByDocumentIdErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2538,6 +2548,7 @@ export type GetDatasetsByDatasetIdDocumentsByDocumentIdData = { } export type GetDatasetsByDatasetIdDocumentsByDocumentIdErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2763,6 +2774,7 @@ export type PostDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChild } export type PostDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2790,6 +2802,7 @@ export type DeleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChi export type DeleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksByChildChunkIdErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2818,6 +2831,7 @@ export type PatchDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChil export type PatchDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksByChildChunkIdErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2845,6 +2859,7 @@ export type PostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFileData = { } export type PostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFileErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2868,6 +2883,7 @@ export type PostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByTextData = { } export type PostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByTextErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2894,6 +2910,7 @@ export type PostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFile2Data = { } export type PostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFile2Errors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -2939,9 +2956,11 @@ export type PostDatasetsByDatasetIdHitTestingData = { } export type PostDatasetsByDatasetIdHitTestingErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown + 500: unknown } export type PostDatasetsByDatasetIdHitTestingResponses = { @@ -3099,6 +3118,7 @@ export type GetDatasetsByDatasetIdPipelineDatasourcePluginsData = { export type GetDatasetsByDatasetIdPipelineDatasourcePluginsErrors = { 401: unknown 403: unknown + 404: unknown } export type GetDatasetsByDatasetIdPipelineDatasourcePluginsResponses = { @@ -3121,6 +3141,7 @@ export type PostDatasetsByDatasetIdPipelineDatasourceNodesByNodeIdRunData = { export type PostDatasetsByDatasetIdPipelineDatasourceNodesByNodeIdRunErrors = { 401: unknown 403: unknown + 404: unknown } export type PostDatasetsByDatasetIdPipelineDatasourceNodesByNodeIdRunResponses = { @@ -3142,6 +3163,8 @@ export type PostDatasetsByDatasetIdPipelineRunData = { export type PostDatasetsByDatasetIdPipelineRunErrors = { 401: unknown 403: unknown + 404: unknown + 500: unknown } export type PostDatasetsByDatasetIdPipelineRunResponses = { @@ -3161,9 +3184,11 @@ export type PostDatasetsByDatasetIdRetrieveData = { } export type PostDatasetsByDatasetIdRetrieveErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown + 500: unknown } export type PostDatasetsByDatasetIdRetrieveResponses = { @@ -3347,6 +3372,7 @@ export type GetMessagesData = { } export type GetMessagesErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -3433,6 +3459,7 @@ export type GetParametersData = { } export type GetParametersErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -3498,6 +3525,7 @@ export type GetWorkflowByTaskIdEventsData = { } export type GetWorkflowByTaskIdEventsErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -3569,6 +3597,7 @@ export type GetWorkflowsRunByWorkflowRunIdData = { } export type GetWorkflowsRunByWorkflowRunIdErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown @@ -3591,6 +3620,7 @@ export type PostWorkflowsTasksByTaskIdStopData = { } export type PostWorkflowsTasksByTaskIdStopErrors = { + 400: unknown 401: unknown 403: unknown 404: unknown diff --git a/packages/contracts/generated/api/service/zod.gen.ts b/packages/contracts/generated/api/service/zod.gen.ts index 9eff6e5d336..efc05030887 100644 --- a/packages/contracts/generated/api/service/zod.gen.ts +++ b/packages/contracts/generated/api/service/zod.gen.ts @@ -2215,7 +2215,7 @@ export const zGetAppFeedbacksQuery = z.object({ }) /** - * Feedbacks retrieved successfully + * A list of application feedbacks. */ export const zGetAppFeedbacksResponse = zAppFeedbackListResponse @@ -2226,7 +2226,7 @@ export const zPostAppsAnnotationReplyByActionPath = z.object({ }) /** - * Action completed successfully + * Annotation reply settings task initiated. */ export const zPostAppsAnnotationReplyByActionResponse = zAnnotationJobStatusResponse @@ -2236,7 +2236,7 @@ export const zGetAppsAnnotationReplyByActionStatusByJobIdPath = z.object({ }) /** - * Job status retrieved successfully + * Successfully retrieved task status. */ export const zGetAppsAnnotationReplyByActionStatusByJobIdResponse = zAnnotationJobStatusResponse @@ -2247,14 +2247,14 @@ export const zGetAppsAnnotationsQuery = z.object({ }) /** - * Annotations retrieved successfully + * Successfully retrieved annotation list. */ export const zGetAppsAnnotationsResponse = zAnnotationList export const zPostAppsAnnotationsBody = zAnnotationCreatePayload /** - * Annotation created successfully + * Annotation created successfully. */ export const zPostAppsAnnotationsResponse = zAnnotation @@ -2263,7 +2263,7 @@ export const zDeleteAppsAnnotationsByAnnotationIdPath = z.object({ }) /** - * Annotation deleted successfully + * Annotation deleted successfully. */ export const zDeleteAppsAnnotationsByAnnotationIdResponse = z.void() @@ -2274,7 +2274,7 @@ export const zPutAppsAnnotationsByAnnotationIdPath = z.object({ }) /** - * Annotation updated successfully + * Annotation updated successfully. */ export const zPutAppsAnnotationsByAnnotationIdResponse = zAnnotation @@ -2284,14 +2284,17 @@ export const zPostAudioToTextBody = z.object({ }) /** - * Audio successfully transcribed + * Successfully converted audio to text. */ export const zPostAudioToTextResponse = zAudioTranscriptResponse export const zPostChatMessagesBody = zChatRequestPayloadWithUser /** - * Message sent successfully + * Successful response. The content type and structure depend on the `response_mode` parameter in the request. + * + * - If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object. + * - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of Server-Sent Events. */ export const zPostChatMessagesResponse = zGeneratedAppResponse @@ -2309,7 +2312,10 @@ export const zPostChatMessagesByTaskIdStopResponse = zSimpleResultResponse export const zPostCompletionMessagesBody = zCompletionRequestPayloadWithUser /** - * Completion created successfully + * Successful response. The content type and structure depend on the `response_mode` parameter in the request. + * + * - If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` object. + * - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkCompletionEvent` objects. */ export const zPostCompletionMessagesResponse = zGeneratedAppResponse @@ -2335,7 +2341,7 @@ export const zGetConversationsQuery = z.object({ }) /** - * Conversations retrieved successfully + * Successfully retrieved conversations list. */ export const zGetConversationsResponse = zConversationInfiniteScrollPagination @@ -2346,7 +2352,7 @@ export const zDeleteConversationsByCIdPath = z.object({ }) /** - * Conversation deleted successfully + * Conversation deleted successfully. */ export const zDeleteConversationsByCIdResponse = z.void() @@ -2357,7 +2363,7 @@ export const zPostConversationsByCIdNamePath = z.object({ }) /** - * Conversation renamed successfully + * Conversation renamed successfully. */ export const zPostConversationsByCIdNameResponse = zSimpleConversation @@ -2373,7 +2379,7 @@ export const zGetConversationsByCIdVariablesQuery = z.object({ }) /** - * Variables retrieved successfully + * Successfully retrieved conversation variables. */ export const zGetConversationsByCIdVariablesResponse = zConversationVariableInfiniteScrollPaginationResponse @@ -2387,7 +2393,7 @@ export const zPutConversationsByCIdVariablesByVariableIdPath = z.object({ }) /** - * Variable updated successfully + * Variable updated successfully. */ export const zPutConversationsByCIdVariablesByVariableIdResponse = zConversationVariableResponse @@ -2400,14 +2406,14 @@ export const zGetDatasetsQuery = z.object({ }) /** - * Datasets retrieved successfully + * List of knowledge bases. */ export const zGetDatasetsResponse = zDatasetListResponse export const zPostDatasetsBody = zDatasetCreatePayload /** - * Dataset created successfully + * Knowledge base created successfully. */ export const zPostDatasetsResponse = zDatasetDetailResponse @@ -2416,47 +2422,47 @@ export const zPostDatasetsPipelineFileUploadBody = z.object({ }) /** - * File uploaded successfully + * File uploaded successfully. */ export const zPostDatasetsPipelineFileUploadResponse = zPipelineUploadFileResponse export const zDeleteDatasetsTagsBody = zTagDeletePayload /** - * Tag deleted successfully + * Success. */ export const zDeleteDatasetsTagsResponse = z.void() /** - * Tags retrieved successfully + * List of tags. */ export const zGetDatasetsTagsResponse = zKnowledgeTagListResponse export const zPatchDatasetsTagsBody = zTagUpdatePayload /** - * Tag updated successfully + * Tag updated successfully. */ export const zPatchDatasetsTagsResponse = zKnowledgeTagResponse export const zPostDatasetsTagsBody = zTagCreatePayload /** - * Tag created successfully + * Tag created successfully. */ export const zPostDatasetsTagsResponse = zKnowledgeTagResponse export const zPostDatasetsTagsBindingBody = zTagBindingPayload /** - * Tags bound successfully + * Success. */ export const zPostDatasetsTagsBindingResponse = z.void() export const zPostDatasetsTagsUnbindingBody = zTagUnbindingPayload /** - * Tags unbound successfully + * Success. */ export const zPostDatasetsTagsUnbindingResponse = z.void() @@ -2465,7 +2471,7 @@ export const zDeleteDatasetsByDatasetIdPath = z.object({ }) /** - * Dataset deleted successfully + * Success. */ export const zDeleteDatasetsByDatasetIdResponse = z.void() @@ -2474,7 +2480,7 @@ export const zGetDatasetsByDatasetIdPath = z.object({ }) /** - * Dataset retrieved successfully + * Knowledge base details. */ export const zGetDatasetsByDatasetIdResponse = zDatasetDetailWithPartialMembersResponse @@ -2485,7 +2491,7 @@ export const zPatchDatasetsByDatasetIdPath = z.object({ }) /** - * Dataset updated successfully + * Knowledge base updated successfully. */ export const zPatchDatasetsByDatasetIdResponse = zDatasetDetailWithPartialMembersResponse @@ -2499,7 +2505,7 @@ export const zPostDatasetsByDatasetIdDocumentCreateByFilePath = z.object({ }) /** - * Document created successfully + * Document created successfully. */ export const zPostDatasetsByDatasetIdDocumentCreateByFileResponse = zDocumentAndBatchResponse @@ -2510,7 +2516,7 @@ export const zPostDatasetsByDatasetIdDocumentCreateByTextPath = z.object({ }) /** - * Document created successfully + * Document created successfully. */ export const zPostDatasetsByDatasetIdDocumentCreateByTextResponse = zDocumentAndBatchResponse @@ -2524,7 +2530,7 @@ export const zPostDatasetsByDatasetIdDocumentCreateByFile2Path = z.object({ }) /** - * Document created successfully + * Document created successfully. */ export const zPostDatasetsByDatasetIdDocumentCreateByFile2Response = zDocumentAndBatchResponse @@ -2551,7 +2557,7 @@ export const zGetDatasetsByDatasetIdDocumentsQuery = z.object({ }) /** - * Documents retrieved successfully + * List of documents. */ export const zGetDatasetsByDatasetIdDocumentsResponse = zDocumentListResponse @@ -2562,7 +2568,7 @@ export const zPostDatasetsByDatasetIdDocumentsDownloadZipPath = z.object({ }) /** - * ZIP archive generated successfully + * ZIP archive containing the requested documents. */ export const zPostDatasetsByDatasetIdDocumentsDownloadZipResponse = z.custom() @@ -2573,7 +2579,7 @@ export const zPostDatasetsByDatasetIdDocumentsMetadataPath = z.object({ }) /** - * Documents metadata updated successfully + * Document metadata updated successfully. */ export const zPostDatasetsByDatasetIdDocumentsMetadataResponse = zDatasetMetadataActionResponse @@ -2595,7 +2601,7 @@ export const zGetDatasetsByDatasetIdDocumentsByBatchIndexingStatusPath = z.objec }) /** - * Indexing status retrieved successfully + * Indexing status for documents in the batch. */ export const zGetDatasetsByDatasetIdDocumentsByBatchIndexingStatusResponse = zDocumentStatusListResponse @@ -2606,7 +2612,7 @@ export const zDeleteDatasetsByDatasetIdDocumentsByDocumentIdPath = z.object({ }) /** - * Document deleted successfully + * Success. */ export const zDeleteDatasetsByDatasetIdDocumentsByDocumentIdResponse = z.void() @@ -2620,7 +2626,7 @@ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdQuery = z.object({ }) /** - * Document retrieved successfully + * Document details. The response shape varies based on the `metadata` query parameter. When `metadata` is `only`, only `id`, `doc_type`, and `doc_metadata` are returned. When `metadata` is `without`, `doc_type` and `doc_metadata` are omitted. */ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdResponse = zDocumentDetailResponse @@ -2645,7 +2651,7 @@ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdDownloadPath = z.object }) /** - * Download URL generated successfully + * Download URL generated successfully. */ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdDownloadResponse = zUrlResponse @@ -2662,7 +2668,7 @@ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsQuery = z.objec }) /** - * Segments retrieved successfully + * List of chunks. */ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsResponse = zSegmentListResponse @@ -2674,7 +2680,7 @@ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdSegmentsPath = z.objec }) /** - * Segments created successfully + * Chunks created successfully. */ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdSegmentsResponse = zSegmentCreateListResponse @@ -2686,7 +2692,7 @@ export const zDeleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdP }) /** - * Segment deleted successfully + * Success. */ export const zDeleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdResponse = z.void() @@ -2697,7 +2703,7 @@ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdPath }) /** - * Segment retrieved successfully + * Chunk details. */ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdResponse = zSegmentDetailResponse @@ -2712,7 +2718,7 @@ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdPat }) /** - * Segment updated successfully + * Chunk updated successfully. */ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdResponse = zSegmentDetailResponse @@ -2732,7 +2738,7 @@ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChil }) /** - * Child chunks retrieved successfully + * List of child chunks. */ export const zGetDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksResponse = zChildChunkListResponse @@ -2748,7 +2754,7 @@ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChi }) /** - * Child chunk created successfully + * Child chunk created successfully. */ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksResponse = zChildChunkDetailResponse @@ -2762,7 +2768,7 @@ export const zDeleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdC }) /** - * Child chunk deleted successfully + * Success. */ export const zDeleteDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksByChildChunkIdResponse = z.void() @@ -2779,7 +2785,7 @@ export const zPatchDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdCh }) /** - * Child chunk updated successfully + * Child chunk updated successfully. */ export const zPatchDatasetsByDatasetIdDocumentsByDocumentIdSegmentsBySegmentIdChildChunksByChildChunkIdResponse = zChildChunkDetailResponse @@ -2795,7 +2801,7 @@ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFilePath = z.o }) /** - * Document updated successfully + * Document updated successfully. */ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFileResponse = zDocumentAndBatchResponse @@ -2808,7 +2814,7 @@ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByTextPath = z.o }) /** - * Document updated successfully + * Document updated successfully. */ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByTextResponse = zDocumentAndBatchResponse @@ -2824,7 +2830,7 @@ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFile2Path = z. }) /** - * Document updated successfully + * Document updated successfully. */ export const zPostDatasetsByDatasetIdDocumentsByDocumentIdUpdateByFile2Response = zDocumentAndBatchResponse @@ -2849,7 +2855,7 @@ export const zPostDatasetsByDatasetIdHitTestingPath = z.object({ }) /** - * Hit testing results + * Retrieval results. */ export const zPostDatasetsByDatasetIdHitTestingResponse = zHitTestingResponse @@ -2858,7 +2864,7 @@ export const zGetDatasetsByDatasetIdMetadataPath = z.object({ }) /** - * Metadata retrieved successfully + * Metadata fields for the knowledge base. */ export const zGetDatasetsByDatasetIdMetadataResponse = zDatasetMetadataListResponse @@ -2869,7 +2875,7 @@ export const zPostDatasetsByDatasetIdMetadataPath = z.object({ }) /** - * Metadata created successfully + * Metadata field created successfully. */ export const zPostDatasetsByDatasetIdMetadataResponse = zDatasetMetadataResponse @@ -2878,7 +2884,7 @@ export const zGetDatasetsByDatasetIdMetadataBuiltInPath = z.object({ }) /** - * Built-in fields retrieved successfully + * Built-in metadata fields. */ export const zGetDatasetsByDatasetIdMetadataBuiltInResponse = zDatasetMetadataBuiltInFieldsResponse @@ -2888,7 +2894,7 @@ export const zPostDatasetsByDatasetIdMetadataBuiltInByActionPath = z.object({ }) /** - * Action completed successfully + * Built-in metadata field toggled successfully. */ export const zPostDatasetsByDatasetIdMetadataBuiltInByActionResponse = zDatasetMetadataActionResponse @@ -2899,7 +2905,7 @@ export const zDeleteDatasetsByDatasetIdMetadataByMetadataIdPath = z.object({ }) /** - * Metadata deleted successfully + * Success. */ export const zDeleteDatasetsByDatasetIdMetadataByMetadataIdResponse = z.void() @@ -2911,7 +2917,7 @@ export const zPatchDatasetsByDatasetIdMetadataByMetadataIdPath = z.object({ }) /** - * Metadata updated successfully + * Metadata field updated successfully. */ export const zPatchDatasetsByDatasetIdMetadataByMetadataIdResponse = zDatasetMetadataResponse @@ -2924,7 +2930,7 @@ export const zGetDatasetsByDatasetIdPipelineDatasourcePluginsQuery = z.object({ }) /** - * Datasource plugins retrieved successfully + * List of datasource nodes configured in the pipeline. */ export const zGetDatasetsByDatasetIdPipelineDatasourcePluginsResponse = zDatasourcePluginListResponse @@ -2938,7 +2944,7 @@ export const zPostDatasetsByDatasetIdPipelineDatasourceNodesByNodeIdRunPath = z. }) /** - * Datasource node run successfully + * Streaming response with node execution events. */ export const zPostDatasetsByDatasetIdPipelineDatasourceNodesByNodeIdRunResponse = zGeneratedAppResponse @@ -2950,7 +2956,7 @@ export const zPostDatasetsByDatasetIdPipelineRunPath = z.object({ }) /** - * Pipeline run successfully + * Pipeline execution result. Format depends on `response_mode`: streaming returns a `text/event-stream`, blocking returns a JSON object. */ export const zPostDatasetsByDatasetIdPipelineRunResponse = zGeneratedAppResponse @@ -2961,7 +2967,7 @@ export const zPostDatasetsByDatasetIdRetrievePath = z.object({ }) /** - * Hit testing results + * Retrieval results. */ export const zPostDatasetsByDatasetIdRetrieveResponse = zHitTestingResponse @@ -2970,7 +2976,7 @@ export const zGetDatasetsByDatasetIdTagsPath = z.object({ }) /** - * Tags retrieved successfully + * Tags bound to the knowledge base. */ export const zGetDatasetsByDatasetIdTagsResponse = zDatasetBoundTagListResponse @@ -2979,7 +2985,7 @@ export const zGetEndUsersByEndUserIdPath = z.object({ }) /** - * End user retrieved successfully + * End user retrieved successfully. */ export const zGetEndUsersByEndUserIdResponse = zEndUserDetail @@ -2989,7 +2995,7 @@ export const zPostFilesUploadBody = z.object({ }) /** - * File uploaded successfully + * File uploaded successfully. */ export const zPostFilesUploadResponse = zFileResponse @@ -3003,7 +3009,7 @@ export const zGetFilesByFileIdPreviewQuery = z.object({ }) /** - * File retrieved successfully + * 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`. */ export const zGetFilesByFileIdPreviewResponse = z.custom() @@ -3012,7 +3018,7 @@ export const zGetFormHumanInputByFormTokenPath = z.object({ }) /** - * Form retrieved successfully + * Form contents retrieved successfully. */ export const zGetFormHumanInputByFormTokenResponse = zHumanInputFormDefinitionResponse @@ -3023,12 +3029,12 @@ export const zPostFormHumanInputByFormTokenPath = z.object({ }) /** - * Form submitted successfully + * Form submitted successfully. The response body is an empty object. */ export const zPostFormHumanInputByFormTokenResponse = zHumanInputFormSubmitResponse /** - * Application info retrieved successfully + * Basic information of the application. */ export const zGetInfoResponse = zAppInfoResponse @@ -3040,7 +3046,7 @@ export const zGetMessagesQuery = z.object({ }) /** - * Messages retrieved successfully + * Successfully retrieved conversation history. */ export const zGetMessagesResponse = zMessageInfiniteScrollPagination @@ -3069,24 +3075,24 @@ export const zGetMessagesByMessageIdSuggestedQuery = z.object({ export const zGetMessagesByMessageIdSuggestedResponse = zSimpleResultStringListResponse /** - * Metadata retrieved successfully + * Successfully retrieved application meta information. */ export const zGetMetaResponse = zAppMetaResponse /** - * Parameters retrieved successfully + * Application parameters information. */ export const zGetParametersResponse = zParameters /** - * Site configuration retrieved successfully + * WebApp settings of the application. */ export const zGetSiteResponse = zSite export const zPostTextToAudioBody = zTextToAudioPayloadWithUser /** - * Text successfully converted to audio + * Returns the generated audio. Generator responses are streamed by the service as `audio/mpeg`; otherwise the provider output is returned directly. */ export const zPostTextToAudioResponse = z.custom() @@ -3101,7 +3107,7 @@ export const zGetWorkflowByTaskIdEventsQuery = z.object({ }) /** - * SSE event stream + * Server-Sent Events stream. Each event is delivered as `data: {JSON}\n\n`. Event payloads follow the same schemas as the original streaming response. */ export const zGetWorkflowByTaskIdEventsResponse = zEventStreamResponse @@ -3117,14 +3123,17 @@ export const zGetWorkflowsLogsQuery = z.object({ }) /** - * Logs retrieved successfully + * Successfully retrieved workflow logs. */ export const zGetWorkflowsLogsResponse = zWorkflowAppLogPaginationResponse export const zPostWorkflowsRunBody = zWorkflowRunPayloadWithUser /** - * Workflow executed successfully + * Successful response. The content type and structure depend on the `response_mode` parameter in the request. + * + * - If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object. + * - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects. */ export const zPostWorkflowsRunResponse = zGeneratedAppResponse @@ -3133,7 +3142,7 @@ export const zGetWorkflowsRunByWorkflowRunIdPath = z.object({ }) /** - * Workflow run details retrieved successfully + * Successfully retrieved workflow run details. */ export const zGetWorkflowsRunByWorkflowRunIdResponse = zWorkflowRunResponse @@ -3155,7 +3164,10 @@ export const zPostWorkflowsByWorkflowIdRunPath = z.object({ }) /** - * Workflow executed successfully + * Successful response. The content type and structure depend on the `response_mode` parameter in the request. + * + * - If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object. + * - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects. */ export const zPostWorkflowsByWorkflowIdRunResponse = zGeneratedAppResponse @@ -3164,7 +3176,7 @@ export const zGetWorkspacesCurrentModelsModelTypesByModelTypePath = z.object({ }) /** - * Models retrieved successfully + * Available models for the specified type. */ export const zGetWorkspacesCurrentModelsModelTypesByModelTypeResponse = zProviderWithModelsListResponse