openapi_completion.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Completion App API",
    "description": "The text generation application offers non-session support and is ideal for translation, article writing, summarization AI, and more.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "{api_base_url}",
      "description": "The base URL for the Completion App API. Replace {api_base_url} with the actual API base URL provided for your application.",
      "variables": {
        "api_base_url": {
          "default": "https://api.dify.ai/v1",
          "description": "Actual base URL of the API"
        }
      }
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/completion-messages": {
      "post": {
        "summary": "Send Completion Message",
        "description": "Send a request to the text generation application.",
        "operationId": "createCompletionMessage",
        "tags": [
          "Completions"
        ],
        "requestBody": {
          "description": "Request body to create a completion message.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompletionRequest"
              },
              "examples": {
                "streaming_example": {
                  "summary": "Request Example - Streaming mode",
                  "value": {
                    "inputs": {
                      "city": "San Francisco"
                    },
                    "query": "Translate 'hello' to Spanish.",
                    "response_mode": "streaming",
                    "user": "abc-123",
                    "files": [
                      {
                        "type": "image",
                        "transfer_method": "remote_url",
                        "url": "https://cloud.dify.ai/logo/logo-site.png"
                      }
                    ]
                  }
                },
                "blocking_example": {
                  "summary": "Request Example - Blocking mode",
                  "value": {
                    "inputs": {
                      "city": "New York"
                    },
                    "query": "Summarize the following text: ...",
                    "response_mode": "blocking",
                    "user": "def-456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkCompletionEvent` objects.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompletionResponse"
                },
                "examples": {
                  "blockingResponse": {
                    "summary": "Response Example - Blocking mode",
                    "value": {
                      "event": "message",
                      "task_id": "c3800678-a077-43df-a102-53f23ed20b88",
                      "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e",
                      "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
                      "mode": "completion",
                      "answer": "Hello World!...",
                      "metadata": {
                        "usage": {
                          "prompt_tokens": 1033,
                          "prompt_unit_price": "0.001",
                          "prompt_price_unit": "0.001",
                          "prompt_price": "0.0010330",
                          "completion_tokens": 128,
                          "completion_unit_price": "0.002",
                          "completion_price_unit": "0.001",
                          "completion_price": "0.0002560",
                          "total_tokens": 1161,
                          "total_price": "0.0012890",
                          "currency": "USD",
                          "latency": 0.7682376249867957
                        }
                      },
                      "created_at": 1705407629
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkCompletionEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `message_end` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream."
                },
                "examples": {
                  "streamingResponse": {
                    "summary": "Response Example - Streaming mode",
                    "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n"
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.",
            "content": {
              "application/json": {
                "examples": {
                  "app_unavailable": {
                    "summary": "app_unavailable",
                    "value": {
                      "status": 400,
                      "code": "app_unavailable",
                      "message": "App unavailable, please check your app configurations."
                    }
                  },
                  "provider_not_initialize": {
                    "summary": "provider_not_initialize",
                    "value": {
                      "status": 400,
                      "code": "provider_not_initialize",
                      "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
                    }
                  },
                  "provider_quota_exceeded": {
                    "summary": "provider_quota_exceeded",
                    "value": {
                      "status": 400,
                      "code": "provider_quota_exceeded",
                      "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
                    }
                  },
                  "model_currently_not_support": {
                    "summary": "model_currently_not_support",
                    "value": {
                      "status": 400,
                      "code": "model_currently_not_support",
                      "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
                    }
                  },
                  "completion_request_error": {
                    "summary": "completion_request_error",
                    "value": {
                      "status": 400,
                      "code": "completion_request_error",
                      "message": "Completion request failed."
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`too_many_requests` : Too many concurrent requests for this app.",
            "content": {
              "application/json": {
                "examples": {
                  "too_many_requests": {
                    "summary": "too_many_requests",
                    "value": {
                      "status": 429,
                      "code": "too_many_requests",
                      "message": "Too many requests. Please try again later."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "`internal_server_error` : Internal server error.",
            "content": {
              "application/json": {
                "examples": {
                  "internal_server_error": {
                    "summary": "internal_server_error",
                    "value": {
                      "status": 500,
                      "code": "internal_server_error",
                      "message": "Internal server error."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/completion-messages/{task_id}/stop": {
      "post": {
        "summary": "Stop Completion Message Generation",
        "description": "Stops a completion message generation task. Only supported in `streaming` mode.",
        "operationId": "stopGenerate",
        "tags": [
          "Completions"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "description": "Task ID, can be obtained from the streaming chunk return of the [Send Completion Message](/api-reference/completions/send-completion-message) API.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "user"
                ],
                "properties": {
                  "user": {
                    "type": "string",
                    "description": "User identifier, must be consistent with the user passed in the send message interface."
                  }
                }
              },
              "examples": {
                "example": {
                  "summary": "Request Example",
                  "value": {
                    "user": "abc-123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SuccessResult"
          },
          "400": {
            "description": "`app_unavailable` : App unavailable or misconfigured.",
            "content": {
              "application/json": {
                "examples": {
                  "app_unavailable": {
                    "summary": "app_unavailable",
                    "value": {
                      "status": 400,
                      "code": "app_unavailable",
                      "message": "App unavailable, please check your app configurations."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/messages/{message_id}/feedbacks": {
      "post": {
        "operationId": "postMessageFeedback",
        "tags": [
          "Feedback"
        ],
        "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.",
        "parameters": [
          {
            "name": "message_id",
            "in": "path",
            "required": true,
            "description": "Message ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageFeedbackRequest"
              },
              "examples": {
                "likeFeedback": {
                  "summary": "Request Example",
                  "value": {
                    "rating": "like",
                    "user": "abc-123",
                    "content": "This answer was very helpful!"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/SuccessResult"
          },
          "404": {
            "description": "`not_found` : Message does not exist.",
            "content": {
              "application/json": {
                "examples": {
                  "message_not_exists": {
                    "summary": "not_found",
                    "value": {
                      "status": 404,
                      "code": "not_found",
                      "message": "Message Not Exists."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/app/feedbacks": {
      "get": {
        "operationId": "getAppFeedbacks",
        "tags": [
          "Feedback"
        ],
        "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.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of records per page.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 101
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of application feedbacks.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppFeedbacksResponse"
                },
                "examples": {
                  "feedbacksList": {
                    "summary": "Response Example",
                    "value": {
                      "data": [
                        {
                          "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456",
                          "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
                          "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
                          "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
                          "rating": "like",
                          "content": "The response accurately answered my question about product specifications.",
                          "from_source": "user",
                          "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
                          "from_account_id": null,
                          "created_at": "2025-01-16T14:30:29Z",
                          "updated_at": "2025-01-16T14:30:29Z"
                        },
                        {
                          "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678",
                          "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
                          "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603",
                          "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1",
                          "rating": "dislike",
                          "content": "The answer was too vague and did not address the specific pricing question.",
                          "from_source": "user",
                          "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210",
                          "from_account_id": null,
                          "created_at": "2025-01-15T09:12:45Z",
                          "updated_at": "2025-01-15T09:12:45Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/files/upload": {
      "post": {
        "operationId": "uploadFile",
        "tags": [
          "Files"
        ],
        "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.",
        "requestBody": {
          "description": "File upload request. Requires multipart/form-data.",
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file",
                  "user"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The file to be uploaded. Supported types include images, documents, audio, and video."
                  },
                  "user": {
                    "type": "string",
                    "description": "Identifier for the end user, defined by your application's rules and unique within the app. Service API and WebApp user IDs are separate, even when identical."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "File uploaded successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUploadResponse"
                },
                "examples": {
                  "uploadSuccess": {
                    "summary": "Response Example",
                    "value": {
                      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
                      "name": "product-photo.png",
                      "size": 204800,
                      "extension": "png",
                      "mime_type": "image/png",
                      "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
                      "created_at": 1705407629,
                      "preview_url": null,
                      "source_url": null,
                      "original_url": null,
                      "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
                      "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
                      "conversation_id": null,
                      "file_key": "uploads/product-photo.png"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.",
            "content": {
              "application/json": {
                "examples": {
                  "no_file_uploaded": {
                    "summary": "no_file_uploaded",
                    "value": {
                      "status": 400,
                      "code": "no_file_uploaded",
                      "message": "Please upload your file."
                    }
                  },
                  "too_many_files": {
                    "summary": "too_many_files",
                    "value": {
                      "status": 400,
                      "code": "too_many_files",
                      "message": "Only one file is allowed."
                    }
                  },
                  "filename_not_exists_error": {
                    "summary": "filename_not_exists_error",
                    "value": {
                      "status": 400,
                      "code": "filename_not_exists_error",
                      "message": "The specified filename does not exist."
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "`file_too_large` : File size exceeded.",
            "content": {
              "application/json": {
                "examples": {
                  "file_too_large": {
                    "summary": "file_too_large",
                    "value": {
                      "status": 413,
                      "code": "file_too_large",
                      "message": "File size exceeded."
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`unsupported_file_type` : File type not allowed.",
            "content": {
              "application/json": {
                "examples": {
                  "unsupported_file_type": {
                    "summary": "unsupported_file_type",
                    "value": {
                      "status": 415,
                      "code": "unsupported_file_type",
                      "message": "File type not allowed."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/files/{file_id}/preview": {
      "get": {
        "operationId": "previewCompletionFile",
        "tags": [
          "Files"
        ],
        "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.",
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "as_attachment",
            "in": "query",
            "required": false,
            "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "user",
            "in": "query",
            "required": false,
            "description": "User identifier, used for end-user context.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "403": {
            "description": "`file_access_denied` : Access to the requested file is denied.",
            "content": {
              "application/json": {
                "examples": {
                  "file_access_denied": {
                    "summary": "file_access_denied",
                    "value": {
                      "status": 403,
                      "code": "file_access_denied",
                      "message": "Access to the requested file is denied."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`file_not_found` : The requested file was not found.",
            "content": {
              "application/json": {
                "examples": {
                  "file_not_found": {
                    "summary": "file_not_found",
                    "value": {
                      "status": 404,
                      "code": "file_not_found",
                      "message": "The requested file was not found."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/end-users/{end_user_id}": {
      "get": {
        "operationId": "getEndUserCompletion",
        "tags": [
          "End Users"
        ],
        "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)).",
        "parameters": [
          {
            "name": "end_user_id",
            "in": "path",
            "required": true,
            "description": "End user ID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "End user retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EndUserDetail"
                },
                "examples": {
                  "endUserDetail": {
                    "summary": "Response Example",
                    "value": {
                      "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
                      "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
                      "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
                      "type": "service_api",
                      "external_user_id": "abc-123",
                      "name": null,
                      "is_anonymous": false,
                      "session_id": "abc-123",
                      "created_at": "2024-01-16T12:00:29Z",
                      "updated_at": "2024-01-16T12:00:29Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`end_user_not_found` : End user not found.",
            "content": {
              "application/json": {
                "examples": {
                  "end_user_not_found": {
                    "summary": "end_user_not_found",
                    "value": {
                      "status": 404,
                      "code": "end_user_not_found",
                      "message": "End user not found."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/audio-to-text": {
      "post": {
        "operationId": "completionAudioToText",
        "tags": [
          "TTS"
        ],
        "summary": "Convert Audio to Text",
        "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/AudioToTextRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully converted audio to text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioToTextResponse"
                },
                "examples": {
                  "audioToTextSuccess": {
                    "summary": "Response Example",
                    "value": {
                      "text": "Hello, I would like to know more about the iPhone 13 Pro Max."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.",
            "content": {
              "application/json": {
                "examples": {
                  "app_unavailable": {
                    "summary": "app_unavailable",
                    "value": {
                      "status": 400,
                      "code": "app_unavailable",
                      "message": "App unavailable, please check your app configurations."
                    }
                  },
                  "no_audio_uploaded": {
                    "summary": "no_audio_uploaded",
                    "value": {
                      "status": 400,
                      "code": "no_audio_uploaded",
                      "message": "Please upload your audio."
                    }
                  },
                  "provider_not_support_speech_to_text": {
                    "summary": "provider_not_support_speech_to_text",
                    "value": {
                      "status": 400,
                      "code": "provider_not_support_speech_to_text",
                      "message": "Provider not support speech to text."
                    }
                  },
                  "provider_not_initialize": {
                    "summary": "provider_not_initialize",
                    "value": {
                      "status": 400,
                      "code": "provider_not_initialize",
                      "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
                    }
                  },
                  "provider_quota_exceeded": {
                    "summary": "provider_quota_exceeded",
                    "value": {
                      "status": 400,
                      "code": "provider_quota_exceeded",
                      "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
                    }
                  },
                  "model_currently_not_support": {
                    "summary": "model_currently_not_support",
                    "value": {
                      "status": 400,
                      "code": "model_currently_not_support",
                      "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
                    }
                  },
                  "completion_request_error": {
                    "summary": "completion_request_error",
                    "value": {
                      "status": 400,
                      "code": "completion_request_error",
                      "message": "Completion request failed."
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "`audio_too_large` : Audio file size exceeded the limit.",
            "content": {
              "application/json": {
                "examples": {
                  "audio_too_large": {
                    "summary": "audio_too_large",
                    "value": {
                      "status": 413,
                      "code": "audio_too_large",
                      "message": "Audio size exceeded."
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "`unsupported_audio_type` : Audio type is not allowed.",
            "content": {
              "application/json": {
                "examples": {
                  "unsupported_audio_type": {
                    "summary": "unsupported_audio_type",
                    "value": {
                      "status": 415,
                      "code": "unsupported_audio_type",
                      "message": "Audio type not allowed."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "`internal_server_error` : Internal server error.",
            "content": {
              "application/json": {
                "examples": {
                  "internal_server_error": {
                    "summary": "internal_server_error",
                    "value": {
                      "status": 500,
                      "code": "internal_server_error",
                      "message": "Internal server error."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/text-to-audio": {
      "post": {
        "operationId": "textToAudio",
        "tags": [
          "TTS"
        ],
        "summary": "Convert Text to Audio",
        "description": "Convert text to speech.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TextToAudioRequest"
              },
              "examples": {
                "textToAudioExample": {
                  "summary": "Request Example",
                  "value": {
                    "text": "Hello, welcome to our service.",
                    "user": "abc-123",
                    "voice": "alloy",
                    "streaming": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.",
            "content": {
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.",
            "content": {
              "application/json": {
                "examples": {
                  "app_unavailable": {
                    "summary": "app_unavailable",
                    "value": {
                      "status": 400,
                      "code": "app_unavailable",
                      "message": "App unavailable, please check your app configurations."
                    }
                  },
                  "provider_not_initialize": {
                    "summary": "provider_not_initialize",
                    "value": {
                      "status": 400,
                      "code": "provider_not_initialize",
                      "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
                    }
                  },
                  "provider_quota_exceeded": {
                    "summary": "provider_quota_exceeded",
                    "value": {
                      "status": 400,
                      "code": "provider_quota_exceeded",
                      "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
                    }
                  },
                  "model_currently_not_support": {
                    "summary": "model_currently_not_support",
                    "value": {
                      "status": 400,
                      "code": "model_currently_not_support",
                      "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
                    }
                  },
                  "completion_request_error": {
                    "summary": "completion_request_error",
                    "value": {
                      "status": 400,
                      "code": "completion_request_error",
                      "message": "Completion request failed."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "`internal_server_error` : Internal server error.",
            "content": {
              "application/json": {
                "examples": {
                  "internal_server_error": {
                    "summary": "internal_server_error",
                    "value": {
                      "status": 500,
                      "code": "internal_server_error",
                      "message": "Internal server error."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/info": {
      "get": {
        "operationId": "getAppInfo",
        "tags": [
          "Applications"
        ],
        "summary": "Get App Info",
        "description": "Retrieve basic information about this application, including name, description, tags, and mode.",
        "responses": {
          "200": {
            "description": "Basic information of the application.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppInfoResponse"
                },
                "examples": {
                  "appInfo": {
                    "summary": "Response Example",
                    "value": {
                      "name": "My Completion App",
                      "description": "A helpful customer service chatbot.",
                      "tags": [
                        "customer-service",
                        "chatbot"
                      ],
                      "mode": "completion",
                      "author_name": "Dify Team"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/parameters": {
      "get": {
        "operationId": "getAppParameters",
        "tags": [
          "Applications"
        ],
        "summary": "Get App Parameters",
        "description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.",
        "responses": {
          "200": {
            "description": "Application parameters information.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompletionAppParametersResponse"
                },
                "examples": {
                  "appParameters": {
                    "summary": "Response Example",
                    "value": {
                      "opening_statement": "Hello! How can I help you today?",
                      "suggested_questions": [
                        "What can you do?",
                        "Tell me about your features."
                      ],
                      "suggested_questions_after_answer": {
                        "enabled": true
                      },
                      "speech_to_text": {
                        "enabled": false
                      },
                      "text_to_speech": {
                        "enabled": false,
                        "voice": "alloy",
                        "language": "en-US",
                        "autoPlay": "disabled"
                      },
                      "retriever_resource": {
                        "enabled": true
                      },
                      "annotation_reply": {
                        "enabled": false
                      },
                      "more_like_this": {
                        "enabled": false
                      },
                      "sensitive_word_avoidance": {
                        "enabled": false
                      },
                      "user_input_form": [
                        {
                          "text-input": {
                            "label": "City",
                            "variable": "city",
                            "required": true,
                            "default": ""
                          }
                        }
                      ],
                      "file_upload": {
                        "image": {
                          "enabled": true,
                          "number_limits": 3,
                          "detail": "high",
                          "transfer_methods": [
                            "remote_url",
                            "local_file"
                          ]
                        }
                      },
                      "system_parameters": {
                        "file_size_limit": 15,
                        "image_file_size_limit": 10,
                        "audio_file_size_limit": 50,
                        "video_file_size_limit": 100,
                        "workflow_file_upload_limit": 10
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`app_unavailable` : App unavailable or misconfigured.",
            "content": {
              "application/json": {
                "examples": {
                  "app_unavailable": {
                    "summary": "app_unavailable",
                    "value": {
                      "status": 400,
                      "code": "app_unavailable",
                      "message": "App unavailable, please check your app configurations."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/meta": {
      "get": {
        "operationId": "getCompletionAppMeta",
        "tags": [
          "Applications"
        ],
        "summary": "Get App Meta",
        "description": "Retrieve metadata about this application, including tool icons and other configuration details.",
        "responses": {
          "200": {
            "description": "Successfully retrieved application meta information.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppMetaResponse"
                },
                "examples": {
                  "appMeta": {
                    "summary": "Response Example",
                    "value": {
                      "tool_icons": {
                        "dalle3": "https://example.com/icons/dalle3.png",
                        "calculator": {
                          "background": "#4A90D9",
                          "content": "🧮"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/site": {
      "get": {
        "operationId": "getWebAppSettings",
        "tags": [
          "Applications"
        ],
        "summary": "Get App WebApp Settings",
        "description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.",
        "responses": {
          "200": {
            "description": "WebApp settings of the application.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebAppSettingsResponse"
                },
                "examples": {
                  "webAppSettings": {
                    "summary": "Response Example",
                    "value": {
                      "title": "My Chat App",
                      "chat_color_theme": "#4A90D9",
                      "chat_color_theme_inverted": false,
                      "icon_type": "emoji",
                      "icon": "🤖",
                      "icon_background": "#FFFFFF",
                      "icon_url": null,
                      "description": "A helpful customer service chatbot.",
                      "copyright": "2025 Dify",
                      "privacy_policy": "https://example.com/privacy",
                      "custom_disclaimer": "",
                      "default_language": "en-US",
                      "show_workflow_steps": false,
                      "use_icon_as_answer_icon": true
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`forbidden` : Site not found for this application or the workspace has been archived.",
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "summary": "forbidden",
                    "value": {
                      "status": 403,
                      "code": "forbidden",
                      "message": "Forbidden."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API_KEY",
        "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**"
      }
    },
    "responses": {
      "SuccessResult": {
        "description": "Operation successful.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "result": {
                  "type": "string",
                  "description": "Result status."
                }
              }
            },
            "examples": {
              "success": {
                "summary": "Response Example",
                "value": {
                  "result": "success"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "CompletionRequest": {
        "type": "object",
        "required": [
          "inputs",
          "user"
        ],
        "properties": {
          "inputs": {
            "type": "object",
            "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.",
            "additionalProperties": true
          },
          "query": {
            "type": "string",
            "default": "",
            "description": "The input text to be processed. This is a legacy parameter; in newer apps, the query should be passed inside the `inputs` object."
          },
          "response_mode": {
            "type": "string",
            "enum": [
              "streaming",
              "blocking"
            ],
            "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior."
          },
          "user": {
            "type": "string",
            "description": "User identifier, unique within the application. This identifier scopes data access — messages and files are only visible when queried with the same `user` value."
          },
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InputFileObject"
            },
            "description": "File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`."
          }
        }
      },
      "InputFileObject": {
        "type": "object",
        "required": [
          "type",
          "transfer_method"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "image",
              "document",
              "audio",
              "video",
              "custom"
            ],
            "description": "File type."
          },
          "transfer_method": {
            "type": "string",
            "enum": [
              "remote_url",
              "local_file"
            ],
            "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file."
          },
          "url": {
            "type": "string",
            "format": "url",
            "description": "File URL (when `transfer_method` is `remote_url`)."
          },
          "upload_file_id": {
            "type": "string",
            "description": "Uploaded file ID, obtained by uploading through the [Upload File](/api-reference/files/upload-file) API in advance (when `transfer_method` is `local_file`)."
          }
        },
        "anyOf": [
          {
            "properties": {
              "transfer_method": {
                "enum": [
                  "remote_url"
                ]
              },
              "url": {
                "type": "string",
                "format": "url"
              }
            },
            "required": [
              "url"
            ],
            "not": {
              "required": [
                "upload_file_id"
              ]
            }
          },
          {
            "properties": {
              "transfer_method": {
                "enum": [
                  "local_file"
                ]
              },
              "upload_file_id": {
                "type": "string"
              }
            },
            "required": [
              "upload_file_id"
            ],
            "not": {
              "required": [
                "url"
              ]
            }
          }
        ]
      },
      "CompletionResponse": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "description": "Event type, fixed as `message`."
          },
          "task_id": {
            "type": "string",
            "format": "uuid",
            "description": "Task ID for request tracking and the [Stop Completion Message Generation](/api-reference/completions/stop-completion-message-generation) API."
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique ID of this response event."
          },
          "message_id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints."
          },
          "mode": {
            "type": "string",
            "description": "App mode, fixed as `completion`."
          },
          "answer": {
            "type": "string",
            "description": "Complete response content."
          },
          "metadata": {
            "type": "object",
            "description": "Metadata including usage and retriever resources.",
            "properties": {
              "usage": {
                "$ref": "#/components/schemas/Usage"
              },
              "retriever_resources": {
                "type": "array",
                "description": "List of retriever resources used.",
                "items": {
                  "$ref": "#/components/schemas/RetrieverResource"
                }
              }
            }
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Message creation timestamp (Unix epoch seconds)."
          }
        }
      },
      "ChunkCompletionEvent": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "message",
              "message_end",
              "message_file",
              "tts_message",
              "tts_message_end",
              "message_replace",
              "error",
              "ping"
            ],
            "description": "The type of streaming event."
          }
        },
        "discriminator": {
          "propertyName": "event",
          "mapping": {
            "message": "#/components/schemas/StreamEventMessage",
            "message_end": "#/components/schemas/StreamEventMessageEnd",
            "message_file": "#/components/schemas/StreamEventMessageFile",
            "tts_message": "#/components/schemas/StreamEventTtsMessage",
            "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd",
            "message_replace": "#/components/schemas/StreamEventMessageReplace",
            "error": "#/components/schemas/StreamEventError",
            "ping": "#/components/schemas/StreamEventPing"
          }
        }
      },
      "StreamEventBase": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "format": "uuid",
            "description": "Task ID."
          },
          "message_id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique message ID."
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Creation timestamp."
          }
        }
      },
      "StreamEventMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ChunkCompletionEvent"
          },
          {
            "$ref": "#/components/schemas/StreamEventBase"
          },
          {
            "type": "object",
            "description": "LLM returns text chunk event.",
            "properties": {
              "answer": {
                "type": "string",
                "description": "LLM returned text chunk content."
              }
            }
          }
        ]
      },
      "StreamEventMessageEnd": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ChunkCompletionEvent"
          },
          {
            "$ref": "#/components/schemas/StreamEventBase"
          },
          {
            "type": "object",
            "description": "Message end event, receiving this event means streaming has ended.",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Unique message ID."
              },
              "metadata": {
                "type": "object",
                "description": "Metadata including usage and retriever resources.",
                "properties": {
                  "usage": {
                    "$ref": "#/components/schemas/Usage"
                  },
                  "retriever_resources": {
                    "type": "array",
                    "description": "List of retriever resources used.",
                    "items": {
                      "$ref": "#/components/schemas/RetrieverResource"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "StreamEventTtsMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ChunkCompletionEvent"
          },
          {
            "$ref": "#/components/schemas/StreamEventBase"
          },
          {
            "type": "object",
            "description": "TTS audio stream event (base64 encoded MP3). Available if auto-play is enabled.",
            "properties": {
              "audio": {
                "type": "string",
                "format": "byte",
                "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file."
              }
            }
          }
        ]
      },
      "StreamEventTtsMessageEnd": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ChunkCompletionEvent"
          },
          {
            "$ref": "#/components/schemas/StreamEventBase"
          },
          {
            "type": "object",
            "description": "TTS audio stream end event.",
            "properties": {
              "audio": {
                "type": "string",
                "description": "Empty string. Signals the end of the audio stream."
              }
            }
          }
        ]
      },
      "StreamEventMessageFile": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ChunkCompletionEvent"
          },
          {
            "type": "object",
            "description": "Message file event, a new file created by a tool.",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "File unique ID."
              },
              "type": {
                "type": "string",
                "description": "File type, e.g. `image`."
              },
              "belongs_to": {
                "type": "string",
                "enum": [
                  "assistant"
                ],
                "description": "Who this file belongs to, always `assistant` here."
              },
              "url": {
                "type": "string",
                "format": "url",
                "description": "Remote URL of the file."
              }
            }
          }
        ]
      },
      "StreamEventMessageReplace": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ChunkCompletionEvent"
          },
          {
            "$ref": "#/components/schemas/StreamEventBase"
          },
          {
            "type": "object",
            "description": "Message content replacement event (e.g., due to content moderation).",
            "properties": {
              "answer": {
                "type": "string",
                "description": "Replacement content."
              },
              "reason": {
                "type": "string",
                "description": "Reason for the content replacement."
              }
            }
          }
        ]
      },
      "StreamEventError": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ChunkCompletionEvent"
          },
          {
            "$ref": "#/components/schemas/StreamEventBase"
          },
          {
            "type": "object",
            "description": "Error event during streaming.",
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code."
              },
              "code": {
                "type": "string",
                "description": "Error code."
              },
              "message": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        ]
      },
      "StreamEventPing": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ChunkCompletionEvent"
          },
          {
            "type": "object",
            "description": "Ping event to keep connection alive."
          }
        ]
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": {
            "type": "integer",
            "description": "Number of tokens in the prompt."
          },
          "prompt_unit_price": {
            "type": "string",
            "format": "decimal",
            "description": "Unit price per prompt token."
          },
          "prompt_price_unit": {
            "type": "string",
            "format": "decimal",
            "description": "Price unit for prompt tokens."
          },
          "prompt_price": {
            "type": "string",
            "format": "decimal",
            "description": "Total price for prompt tokens."
          },
          "completion_tokens": {
            "type": "integer",
            "description": "Number of tokens in the completion."
          },
          "completion_unit_price": {
            "type": "string",
            "format": "decimal",
            "description": "Unit price per completion token."
          },
          "completion_price_unit": {
            "type": "string",
            "format": "decimal",
            "description": "Price unit for completion tokens."
          },
          "completion_price": {
            "type": "string",
            "format": "decimal",
            "description": "Total price for completion tokens."
          },
          "total_tokens": {
            "type": "integer",
            "description": "Total number of tokens used."
          },
          "total_price": {
            "type": "string",
            "format": "decimal",
            "description": "Total price for all tokens."
          },
          "currency": {
            "type": "string",
            "description": "Currency for pricing."
          },
          "latency": {
            "type": "number",
            "format": "double",
            "description": "Latency in seconds."
          }
        }
      },
      "RetrieverResource": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique ID of the retriever resource."
          },
          "message_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the message this resource belongs to."
          },
          "position": {
            "type": "integer",
            "description": "Position of the resource in the list."
          },
          "dataset_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the knowledge base."
          },
          "dataset_name": {
            "type": "string",
            "description": "Name of the knowledge base."
          },
          "document_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the document."
          },
          "document_name": {
            "type": "string",
            "description": "Name of the document."
          },
          "data_source_type": {
            "type": "string",
            "description": "Type of the data source."
          },
          "segment_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the specific chunk within the document."
          },
          "score": {
            "type": "number",
            "format": "float",
            "description": "Similarity score of the resource."
          },
          "hit_count": {
            "type": "integer",
            "description": "Number of times this chunk was hit."
          },
          "word_count": {
            "type": "integer",
            "description": "Word count of the chunk."
          },
          "segment_position": {
            "type": "integer",
            "description": "Position of the chunk within the document."
          },
          "index_node_hash": {
            "type": "string",
            "description": "Hash of the index node."
          },
          "content": {
            "type": "string",
            "description": "Content snippet from the resource."
          },
          "summary": {
            "type": "string",
            "nullable": true,
            "description": "Summary of the chunk content."
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Creation timestamp (Unix epoch seconds)."
          }
        }
      },
      "FileUploadResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique file ID."
          },
          "name": {
            "type": "string",
            "description": "File name."
          },
          "size": {
            "type": "integer",
            "description": "File size in bytes."
          },
          "extension": {
            "type": "string",
            "nullable": true,
            "description": "File extension."
          },
          "mime_type": {
            "type": "string",
            "nullable": true,
            "description": "MIME type of the file."
          },
          "created_by": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "ID of the user who uploaded the file."
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Upload timestamp (Unix epoch seconds)."
          },
          "preview_url": {
            "type": "string",
            "nullable": true,
            "description": "Preview URL for the file."
          },
          "source_url": {
            "type": "string",
            "nullable": true,
            "description": "Source URL of the file."
          },
          "original_url": {
            "type": "string",
            "nullable": true,
            "description": "Original URL of the file."
          },
          "user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "ID of the associated user."
          },
          "tenant_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "ID of the associated tenant."
          },
          "conversation_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "ID of the associated conversation."
          },
          "file_key": {
            "type": "string",
            "nullable": true,
            "description": "Storage key for the file."
          }
        }
      },
      "EndUserDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "End user ID."
          },
          "tenant_id": {
            "type": "string",
            "format": "uuid",
            "description": "Tenant ID."
          },
          "app_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Application ID."
          },
          "type": {
            "type": "string",
            "description": "End user type. Always `service_api` for Service API users."
          },
          "external_user_id": {
            "type": "string",
            "nullable": true,
            "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Completion Message](/api-reference/completions/send-completion-message))."
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "End user name."
          },
          "is_anonymous": {
            "type": "boolean",
            "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request."
          },
          "session_id": {
            "type": "string",
            "description": "Session identifier. Defaults to the `external_user_id` value."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Creation timestamp."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp."
          }
        }
      },
      "MessageFeedbackRequest": {
        "type": "object",
        "description": "Request body for submitting message feedback.",
        "required": [
          "user"
        ],
        "properties": {
          "rating": {
            "type": "string",
            "enum": [
              "like",
              "dislike",
              null
            ],
            "nullable": true,
            "description": "Feedback rating. Set to `null` to revoke previously submitted feedback."
          },
          "user": {
            "type": "string",
            "description": "User identifier, defined by the developer, must ensure uniqueness within the application."
          },
          "content": {
            "type": "string",
            "description": "Optional text feedback providing additional detail."
          }
        }
      },
      "AppFeedbacksResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "description": "List of feedback items.",
            "items": {
              "$ref": "#/components/schemas/FeedbackItem"
            }
          }
        }
      },
      "FeedbackItem": {
        "type": "object",
        "description": "A single feedback item.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Feedback ID."
          },
          "app_id": {
            "type": "string",
            "format": "uuid",
            "description": "Application ID."
          },
          "conversation_id": {
            "type": "string",
            "format": "uuid",
            "description": "Conversation ID."
          },
          "message_id": {
            "type": "string",
            "format": "uuid",
            "description": "Message ID."
          },
          "rating": {
            "type": "string",
            "description": "Feedback rating. `like` for positive, `dislike` for negative."
          },
          "content": {
            "type": "string",
            "nullable": true,
            "description": "Optional text feedback."
          },
          "from_source": {
            "type": "string",
            "description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console."
          },
          "from_end_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "End user ID who submitted the feedback. Present when `from_source` is `user`."
          },
          "from_account_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Account ID who submitted the feedback. Present when `from_source` is `admin`."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Creation timestamp."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp."
          }
        }
      },
      "AudioToTextRequest": {
        "type": "object",
        "description": "Request body for audio-to-text conversion.",
        "required": [
          "file"
        ],
        "properties": {
          "file": {
            "type": "string",
            "format": "binary",
            "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `30 MB`."
          },
          "user": {
            "type": "string",
            "description": "User identifier."
          }
        }
      },
      "AudioToTextResponse": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "description": "Output text from speech recognition."
          }
        }
      },
      "TextToAudioRequest": {
        "type": "object",
        "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.",
        "properties": {
          "message_id": {
            "type": "string",
            "format": "uuid",
            "description": "Message ID. Takes priority over `text` when both are provided."
          },
          "text": {
            "type": "string",
            "description": "Speech content to convert."
          },
          "user": {
            "type": "string",
            "description": "User identifier."
          },
          "voice": {
            "type": "string",
            "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default."
          },
          "streaming": {
            "type": "boolean",
            "description": "Whether to enable streaming response."
          }
        }
      },
      "AppInfoResponse": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Application name."
          },
          "description": {
            "type": "string",
            "description": "Application description."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Application tags."
          },
          "mode": {
            "type": "string",
            "description": "Application mode. `completion` for text generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for chatflow apps, `workflow` for workflow apps."
          },
          "author_name": {
            "type": "string",
            "description": "Name of the application author."
          }
        }
      },
      "CompletionAppParametersResponse": {
        "type": "object",
        "properties": {
          "opening_statement": {
            "type": "string",
            "description": "Opening statement displayed at start."
          },
          "suggested_questions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of suggested starter questions."
          },
          "suggested_questions_after_answer": {
            "type": "object",
            "description": "Configuration for suggested questions after answer.",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Whether this feature is enabled."
              }
            }
          },
          "speech_to_text": {
            "type": "object",
            "description": "Speech-to-text configuration.",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Whether this feature is enabled."
              }
            }
          },
          "text_to_speech": {
            "type": "object",
            "description": "Text-to-speech configuration.",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Whether this feature is enabled."
              },
              "voice": {
                "type": "string",
                "description": "Voice identifier for TTS."
              },
              "language": {
                "type": "string",
                "description": "Language for TTS."
              },
              "autoPlay": {
                "type": "string",
                "enum": [
                  "enabled",
                  "disabled"
                ],
                "description": "Auto-play setting."
              }
            }
          },
          "retriever_resource": {
            "type": "object",
            "description": "Retriever resource configuration.",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Whether this feature is enabled."
              }
            }
          },
          "annotation_reply": {
            "type": "object",
            "description": "Annotation reply configuration.",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Whether this feature is enabled."
              }
            }
          },
          "more_like_this": {
            "type": "object",
            "description": "More-like-this configuration.",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Whether this feature is enabled."
              }
            }
          },
          "sensitive_word_avoidance": {
            "type": "object",
            "description": "Sensitive word avoidance configuration.",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Whether this feature is enabled."
              }
            }
          },
          "user_input_form": {
            "type": "array",
            "description": "List of user input form elements.",
            "items": {
              "$ref": "#/components/schemas/UserInputFormItem"
            }
          },
          "file_upload": {
            "type": "object",
            "description": "File upload configuration.",
            "properties": {
              "image": {
                "type": "object",
                "description": "Image upload settings.",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "description": "Whether image upload is enabled."
                  },
                  "number_limits": {
                    "type": "integer",
                    "description": "Maximum number of images."
                  },
                  "detail": {
                    "type": "string",
                    "description": "Image detail level."
                  },
                  "transfer_methods": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "remote_url",
                        "local_file"
                      ]
                    },
                    "description": "Allowed transfer methods."
                  }
                }
              }
            }
          },
          "system_parameters": {
            "type": "object",
            "description": "System-level parameters and limits.",
            "properties": {
              "file_size_limit": {
                "type": "integer",
                "description": "Maximum file size in MB."
              },
              "image_file_size_limit": {
                "type": "integer",
                "description": "Maximum image file size in MB."
              },
              "audio_file_size_limit": {
                "type": "integer",
                "description": "Maximum audio file size in MB."
              },
              "video_file_size_limit": {
                "type": "integer",
                "description": "Maximum video file size in MB."
              },
              "workflow_file_upload_limit": {
                "type": "integer",
                "description": "Maximum number of files for workflow file upload."
              }
            }
          }
        }
      },
      "UserInputFormItem": {
        "type": "object",
        "oneOf": [
          {
            "$ref": "#/components/schemas/TextInputControlWrapper"
          },
          {
            "$ref": "#/components/schemas/ParagraphControlWrapper"
          },
          {
            "$ref": "#/components/schemas/SelectControlWrapper"
          }
        ]
      },
      "TextInputControlWrapper": {
        "title": "Text Input",
        "type": "object",
        "properties": {
          "text-input": {
            "$ref": "#/components/schemas/TextInputControl"
          }
        }
      },
      "ParagraphControlWrapper": {
        "title": "Paragraph",
        "type": "object",
        "properties": {
          "paragraph": {
            "$ref": "#/components/schemas/ParagraphControl"
          }
        }
      },
      "SelectControlWrapper": {
        "title": "Select",
        "type": "object",
        "properties": {
          "select": {
            "$ref": "#/components/schemas/SelectControl"
          }
        }
      },
      "TextInputControl": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Display label for the form field."
          },
          "variable": {
            "type": "string",
            "description": "Variable name used as the key in the `inputs` object."
          },
          "required": {
            "type": "boolean",
            "description": "Whether this field must be filled before submission."
          },
          "default": {
            "type": "string",
            "description": "Default value pre-filled in the form field."
          }
        }
      },
      "ParagraphControl": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Display label for the form field."
          },
          "variable": {
            "type": "string",
            "description": "Variable name used as the key in the `inputs` object."
          },
          "required": {
            "type": "boolean",
            "description": "Whether this field must be filled before submission."
          },
          "default": {
            "type": "string",
            "description": "Default value pre-filled in the form field."
          }
        }
      },
      "SelectControl": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Display label for the form field."
          },
          "variable": {
            "type": "string",
            "description": "Variable name used as the key in the `inputs` object."
          },
          "required": {
            "type": "boolean",
            "description": "Whether a selection must be made before submission."
          },
          "default": {
            "type": "string",
            "description": "Default selected value."
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of selectable values for this form control."
          }
        }
      },
      "AppMetaResponse": {
        "type": "object",
        "properties": {
          "tool_icons": {
            "type": "object",
            "additionalProperties": {
              "oneOf": [
                {
                  "title": "Icon URL",
                  "type": "string",
                  "format": "url",
                  "description": "URL of the icon."
                },
                {
                  "$ref": "#/components/schemas/ToolIconDetail"
                }
              ]
            },
            "description": "Tool icons. Keys are tool names."
          }
        }
      },
      "ToolIconDetail": {
        "title": "Emoji Icon",
        "type": "object",
        "description": "Detail of a tool icon using emoji.",
        "properties": {
          "background": {
            "type": "string",
            "description": "Background color in hex format."
          },
          "content": {
            "type": "string",
            "description": "Emoji content."
          }
        }
      },
      "WebAppSettingsResponse": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "WebApp title."
          },
          "chat_color_theme": {
            "type": "string",
            "description": "Chat color theme."
          },
          "chat_color_theme_inverted": {
            "type": "boolean",
            "description": "Whether the chat color theme is inverted."
          },
          "icon_type": {
            "type": "string",
            "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons."
          },
          "icon": {
            "type": "string",
            "description": "Icon content (emoji or image ID)."
          },
          "icon_background": {
            "type": "string",
            "description": "Icon background color."
          },
          "icon_url": {
            "type": "string",
            "format": "url",
            "nullable": true,
            "description": "URL of the icon image."
          },
          "description": {
            "type": "string",
            "description": "WebApp description."
          },
          "copyright": {
            "type": "string",
            "description": "Copyright text."
          },
          "privacy_policy": {
            "type": "string",
            "description": "Privacy policy URL."
          },
          "custom_disclaimer": {
            "type": "string",
            "description": "Custom disclaimer text."
          },
          "default_language": {
            "type": "string",
            "description": "Default language code."
          },
          "show_workflow_steps": {
            "type": "boolean",
            "description": "Whether to show workflow steps."
          },
          "use_icon_as_answer_icon": {
            "type": "boolean",
            "description": "Whether to use the app icon as the answer icon."
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Completions",
      "description": "Operations related to text generation and completion."
    },
    {
      "name": "Files",
      "description": "Operations related to file management."
    },
    {
      "name": "End Users",
      "description": "Operations related to end user information."
    },
    {
      "name": "Feedback",
      "description": "Operations related to user feedback."
    },
    {
      "name": "TTS",
      "description": "Operations related to Text-to-Speech and Speech-to-Text."
    },
    {
      "name": "Applications",
      "description": "Operations to retrieve application settings and information."
    }
  ]
}