mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-07-23 12:55:46 -04:00
Riskey
32e1b169da
* docs: correct HITL API integration flow and sync translations
- Fix the claim that the resume endpoint differs per app type (same
endpoint; only the entry endpoint differs)
- Tie workflow_run_id guidance to the human_input_required event
(chatflow message chunks don't carry it)
- Require the same user when resuming the event stream (mismatch
returns 404); add include_state_snapshot and continue_on_pause
guidance
- Note at the capture step that a null form_token means Email delivery
- Soften the upload-time validation claim to file size limits
- Split long paragraphs; align zh endpoint name with the reference page
* fix: correct API references against verified backend behavior
Audit of the Service API specs against dify hotfix/1.15.0-fix.1, with
every change code-verified and the serious items adversarially
confirmed. Applies to en/zh/ja.
- Add curl samples for GET endpoints with required query params
(Mintlify omits query params from generated snippets)
- Document 401 once in every spec's auth scheme description
- Correct wrong facts: workflow run detail returns inputs as a JSON
string; DELETE /conversations requires a JSON body; audio-to-text
accepts audio/{mp3,m4a,wav,amr,mpga} by MIME type; workflow log
created_by_account filters by email; triggered_from values are
app-run/webhook/schedule/plugin; stop endpoints' user semantics
differ per app type
- Remove unreachable docs: phantom text_replace SSE event, annotation
403, file preview endpoint in the workflow spec, invented
score_threshold bounds
- Make upload user optional (DEFAULT-USER fallback), fix upload
response example, add missing invalid_param error
- Declare text_to_speech.autoPlay in parameters responses (prose
values, no response-field enums)
* fix: complete API reference audit for knowledge and completion specs
* feat: add API spec consolidation pipeline
Phase-1 of the API docs consolidation: tooling that merges the five per-app-type Service API specs into one openapi_service.json per language, with every divergence resolved explicitly in resolutions.json and rendering-preserving namespacing for mode-scoped schema families. Includes the audit lint and parity checks (lint taught the new language-prefixed href scheme), hand-merged mode-aware SSE documentation for POST /chat-messages in en/zh/ja, and the New Agent (Beta) virtual nav group with code-verified mode notes.
* feat: consolidate API reference into one spec per language
Emit {en,zh,ja}/api-reference/openapi_service.json (82 ops, 130 components) from the audit-fixed per-app-type specs; wire docs.json to them with explicit per-app-type endpoint lists, x-mint.href URLs (/{lang}/api-reference/{tag}/{summary} with shared English slugs for in-place language switching), 265 redirects covering the legacy en and CJK URLs, per-app-type overview pages including New Agent (Beta), and rewritten legacy API links in 21 MDX bodies. The old five specs per language stay as pipeline input; they are no longer rendered.
* fix: remove dead conversation_completed error from chat specs
ConversationCompletedError is never raised anywhere at the verified 1.15.0 ref (7a4252b3de): controllers catch it, but no service code raises it, so the documented 400 conversation_completed can never fire. Remove the bullet and example from the chat and chatflow /chat-messages docs in en/zh/ja. Found and adversarially confirmed during the New Agent (PR #836) verification; filed on the upstream bug list.
* feat: add membership matrix and restructure nav config
* feat: rename resource tags and update all references
* feat: stamp per-operation availability lines
* feat: wire three-group API navigation
* feat: add app-type page coverage lint
* docs: rewrite chatflow overview as app-type API guide
* docs: polish chatflow overview zh and ja wording
* docs: rewrite workflow overview as app-type API guide
* docs: align workflow overview details across languages
* docs: expand new agent overview into app-type API guide
* docs: use task-oriented heading on new agent overview
* docs: rewrite chatbot and agent overview as app-type API guide
* docs: rewrite text generator overview as app-type API guide
* docs: match end user link text to merged spec summary
* docs: rewrite knowledge overview as app-type API guide
* docs: move knowledge api guide into api reference
* docs: localize ui labels on knowledge overview
* docs: refresh pipeline readme for restructure modes
* docs: name app-type pages in the guides sidebar
* feat: rename zh completion messages tag to match resource framing
* docs: prototype endpoints-first layout on chatflow overview
* docs: correct detail accuracy on chatflow overview
* docs: move human input flow guide into api reference
Move the shared HITL API integration walkthrough from its six per-product
copies into {en,zh,ja}/api-reference/guides/human-input-flow as the first
task guide in the API docs. Guides gains an App Types subgroup (expanded
by default) with the flow guide after it; six redirects cover the old
paths; the Human Input node docs and the chatflow overview link to the
new home.
* fix: update spec links to the moved human input guide
* fix: let spec lint accept mdx guide pages under api-reference
* docs: align chatflow zh and ja overviews to endpoints-first layout
* docs: polish chatflow zh and ja mode terms and hitl wording
* docs: align workflow overviews to endpoints-first layout
* docs: document form expiry path in human input flow guide
* docs: align new agent overviews to endpoints-first layout
* docs: align chatbot and agent overviews to endpoints-first layout
* docs: align text generator overviews to endpoints-first layout
* docs: align knowledge overviews to endpoints-first layout
* docs: correct built-in metadata examples and agent heading
* docs: flatten app-type pages directly under guides
* docs: make guide pages self-contained and trim reference detail
* docs: add get started guide and retire developing-with-apis
* docs: update new agent api behavior for latest main
New Agent behavior re-verified against dify origin/main (f3ba2846):
agent_thought events now stream through the Service API carrying the
model's reasoning steps and tool calls; a new agent_not_published 400
fires on Send Chat Message and Get App Parameters; the files claim is
softened to contents-not-processed (raw references now reach the prompt;
runtime confirmation pending). Streaming-only, message_end metadata, and
the endpoint surface are unchanged.
* docs: audit fixes for get started and human input flow guides
* docs: fix em dash spacing and ja sentence length in get started
* docs: move message_end note to the send endpoint line
* docs: update writing guides and API skill for app-type naming
- Glossary and zh/ja translation guides: Workflow and Chatflow app types stay English (Workflow 应用 / Chatflow アプリ); lowercase workflow localizes to 工作流 / ワークフロー.
- formatting-guide: API reference links use the language prefix with English slugs.
- dify-docs-api-reference skill: Spec Structure documents source specs merged into openapi_service.json by the pipeline.
* feat: add operation sidebar titles and simplify API redirects
- merge_specs stamps x-mint.metadata.sidebarTitle per operation so translated summaries show in the sidebar.
- Redirects reduced to a catch-all to the English API home plus three knowledge-base exceptions.
- memberships, strings, and SSE overrides carry app-type labels (Workflow/Chatflow English, New Agent, API Overviews group).
* docs: correct app-type naming and translations across API specs
- English mode enum labels Chatflow and Workflow apps.
- zh/ja app references use Workflow/Chatflow; New Agent is 新 Agent / 新しい Agent.
- ja knowledge tag データセット becomes ナレッジベース; zh 模型提供商 becomes 模型供应商.
- Regenerate merged openapi_service.json with per-operation sidebar titles.
* docs: add streaming, errors, and end-user identity API guides
- Consume Streaming Responses: response modes, SSE parsing, event dispatch, and reconnect.
- Handle Errors and Rate Limits: the error envelope, status classes, and retry guidance.
- End User Identity: what the user field scopes and why it stays consistent.
- English source with zh and ja translations.
* docs: reconcile API guides and apply app-type naming
- Reader-test fixes and content audit on get-started and the app-type overview pages.
- zh/ja reconciled to the English source.
- Workflow/Chatflow and New Agent naming applied in prose.
* feat: wire API nav and redirects for consolidated guides
- Rename the guides group to API Overviews and register the new guide pages.
- Redirects: catch-all to the English API home plus three product-embedded knowledge-base links to the Knowledge guide.
* fix: normalize zh model-provider term to 模型供应商
Aligns the POSITION_PROVIDER_* descriptions with the canonical glossary term.
* docs: use Info callouts for guide forward-link notes
Wrap the authentication, base URL, and `user` field forward-reference in each app-type guide (agent, chat, chatflow, completion, workflow; en/zh/ja) in an `<Info>` callout.
* refactor: remove one-time analyze mode and verification compose
- Drop the `analyze` mode (design-time spec-overlap analysis) and its helpers; the merge is stable and nothing invokes it.
- Delete `compose.swagger.yml`, the throwaway local code-vs-spec verification stack (flagged in review for inline credentials).
- README: drop the analyze entry and correct the redirect description.
* fix: correct Chatflow naming and reasoning wording in SSE overrides
- Use "Chatflow" (English) for the app type in the `/chat-messages` SSE tables instead of 对话流/チャットフロー, and fix the legacy zh chatflow "对话流工作流" description. Standalone table cells were missed by the earlier app-type rename.
- Describe `reasoning_chunk` as "reasoning content" in en/ja (matching the `reasoning` field and the zh wording) instead of "chain-of-thought".
* docs: refine API guide wording and simplify the human-input example
* docs: standardize Workflow and Chatflow app-type capitalization
Capitalize Chatflow and Workflow when they name an app type; keep "workflow" lowercase for the general engine, graph, or run sense.
* fix: use 供应商 for model provider in the zh Knowledge spec
* fix: rename the Knowledge API nav group to "Knowledge APIs"
* fix: un-deprecate Update Document by Text in the Knowledge spec
* translate: un-deprecate Update Document by Text in zh/ja specs
Mirror the en fix (6802d5eb) into the zh and ja Knowledge specs, source and merged: drop the deprecated flag and the leading Deprecated notice from the update-by-text operation. It is the canonical text-update route; only Update Document by File stays deprecated.
2612 lines
91 KiB
JSON
2612 lines
91 KiB
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": "https://{api_base_url}",
|
|
"description": "Base URL of the Completion App API. For self-hosted deployments, replace it with your own API base URL.",
|
|
"variables": {
|
|
"api_base_url": {
|
|
"default": "api.dify.ai/v1",
|
|
"description": "Host and path of the API base URL, without the `https://` prefix."
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"ApiKeyAuth": []
|
|
}
|
|
],
|
|
"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.\n- `invalid_param` : Required parameter missing or invalid.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"app_unavailable": {
|
|
"summary": "app_unavailable",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "app_unavailable",
|
|
"message": "App unavailable, please check your app configurations."
|
|
}
|
|
},
|
|
"provider_not_initialize": {
|
|
"summary": "provider_not_initialize",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_not_initialize",
|
|
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
|
|
}
|
|
},
|
|
"provider_quota_exceeded": {
|
|
"summary": "provider_quota_exceeded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "provider_quota_exceeded",
|
|
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
|
|
}
|
|
},
|
|
"model_currently_not_support": {
|
|
"summary": "model_currently_not_support",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "model_currently_not_support",
|
|
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
|
|
}
|
|
},
|
|
"completion_request_error": {
|
|
"summary": "completion_request_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "completion_request_error",
|
|
"message": "Completion request failed."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Arg user must be provided."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"description": "`too_many_requests` : Too many concurrent requests for this app.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"too_many_requests": {
|
|
"summary": "too_many_requests",
|
|
"value": {
|
|
"status": 429,
|
|
"code": "too_many_requests",
|
|
"message": "Too many requests. Please try again later. The current maximum concurrent requests allowed for 5b3d4f2a-1c9e-4a7b-8f6d-2e0c9a1b3d4f is 10."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "`internal_server_error` : Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"internal_server_error": {
|
|
"summary": "internal_server_error",
|
|
"value": {
|
|
"status": 500,
|
|
"code": "internal_server_error",
|
|
"message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/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 match the `user` passed when the message was sent: if it differs, the stop silently does nothing and the response still returns success."
|
|
}
|
|
}
|
|
},
|
|
"examples": {
|
|
"example": {
|
|
"summary": "Request Example",
|
|
"value": {
|
|
"user": "abc-123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"$ref": "#/components/responses/SuccessResult"
|
|
},
|
|
"400": {
|
|
"description": "- `app_unavailable` : App unavailable or misconfigured.\n- `invalid_param` : Required parameter missing or invalid.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"app_unavailable": {
|
|
"summary": "app_unavailable",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "app_unavailable",
|
|
"message": "App unavailable, please check your app configurations."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Arg user must be provided."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/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"
|
|
],
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "The file to be uploaded. Supported types include images, documents, audio, and video."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "Identifier for the end user, defined by your application's rules and unique within the app. Service API and WebApp user IDs are separate, even when identical. If omitted, the upload is attributed to the shared `DEFAULT-USER` end user; a file can only be used later by requests carrying the same `user` value."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "File uploaded successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/FileUploadResponse"
|
|
},
|
|
"examples": {
|
|
"uploadSuccess": {
|
|
"summary": "Response Example",
|
|
"value": {
|
|
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
|
|
"name": "product-photo.png",
|
|
"size": 204800,
|
|
"extension": "png",
|
|
"mime_type": "image/png",
|
|
"created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
|
|
"created_at": 1705407629,
|
|
"preview_url": null,
|
|
"source_url": "https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI=",
|
|
"original_url": null,
|
|
"user_id": null,
|
|
"tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
|
|
"conversation_id": null,
|
|
"file_key": null
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.\n- `invalid_param` : The filename contains invalid characters (`/` or `\\`).",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"no_file_uploaded": {
|
|
"summary": "no_file_uploaded",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "no_file_uploaded",
|
|
"message": "Please upload your file."
|
|
}
|
|
},
|
|
"too_many_files": {
|
|
"summary": "too_many_files",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "too_many_files",
|
|
"message": "Only one file is allowed."
|
|
}
|
|
},
|
|
"filename_not_exists_error": {
|
|
"summary": "filename_not_exists_error",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "filename_not_exists_error",
|
|
"message": "The specified filename does not exist."
|
|
}
|
|
},
|
|
"invalid_param": {
|
|
"summary": "invalid_param",
|
|
"value": {
|
|
"status": 400,
|
|
"code": "invalid_param",
|
|
"message": "Filename contains invalid characters"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"413": {
|
|
"description": "`file_too_large` : File size exceeded.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"file_too_large": {
|
|
"summary": "file_too_large",
|
|
"value": {
|
|
"status": 413,
|
|
"code": "file_too_large",
|
|
"message": "File size exceeded."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"415": {
|
|
"description": "`unsupported_file_type` : File type not allowed.",
|
|
"content": {
|
|
"application/json": {
|
|
"examples": {
|
|
"unsupported_file_type": {
|
|
"summary": "unsupported_file_type",
|
|
"value": {
|
|
"status": 415,
|
|
"code": "unsupported_file_type",
|
|
"message": "File type not allowed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/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. The uploaded file's MIME type must be one of `audio/mp3`, `audio/m4a`, `audio/wav`, `audio/amr`, `audio/mpga`; other types, including the common `audio/mpeg`, are rejected with the `unsupported_audio_type` error. File size limit is `30 MB`.",
|
|
"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.** Requests with a missing or invalid API key fail with HTTP `401` and error code `unauthorized`."
|
|
}
|
|
},
|
|
"responses": {
|
|
"SuccessResult": {
|
|
"description": "Operation successful.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"result": {
|
|
"type": "string",
|
|
"description": "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"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"files": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"description": "Files generated during this message, such as model-generated images. `null` when no files were produced.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"related_id": {
|
|
"type": "string",
|
|
"description": "ID of the message file record."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "File type, e.g. `image`."
|
|
},
|
|
"filename": {
|
|
"type": "string",
|
|
"description": "File name."
|
|
},
|
|
"extension": {
|
|
"type": "string",
|
|
"description": "File extension, including the leading dot, e.g. `.png`."
|
|
},
|
|
"mime_type": {
|
|
"type": "string",
|
|
"description": "MIME type of the file."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "File size in bytes."
|
|
},
|
|
"transfer_method": {
|
|
"type": "string",
|
|
"description": "How the file is referenced: `remote_url`, `local_file`, or `tool_file`."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"description": "Accessible URL of the file."
|
|
},
|
|
"upload_file_id": {
|
|
"type": "string",
|
|
"description": "ID of the associated uploaded file."
|
|
},
|
|
"remote_url": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Original remote URL when the file was supplied as a remote URL; otherwise an empty string."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"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 file (typically a model-generated image) produced during generation.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "File unique ID."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "File type, e.g. `image`."
|
|
},
|
|
"belongs_to": {
|
|
"type": "string",
|
|
"enum": [
|
|
"assistant"
|
|
],
|
|
"description": "Who this file belongs to, always `assistant` here."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "url",
|
|
"description": "Remote URL of the file."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"StreamEventMessageReplace": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkCompletionEvent"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/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",
|
|
"description": "Signed URL for downloading the file."
|
|
},
|
|
"original_url": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Original URL of the file."
|
|
},
|
|
"user_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "Unused; always `null`."
|
|
},
|
|
"tenant_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "ID of the associated tenant."
|
|
},
|
|
"conversation_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "ID of the associated conversation."
|
|
},
|
|
"file_key": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Unused; always `null`."
|
|
}
|
|
}
|
|
},
|
|
"EndUserDetail": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "End user ID."
|
|
},
|
|
"tenant_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Tenant ID."
|
|
},
|
|
"app_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"nullable": true,
|
|
"description": "Application ID."
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "End user type. Always `service_api` for Service API users."
|
|
},
|
|
"external_user_id": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send 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. Validated by MIME type: `audio/mp3`, `audio/m4a`, `audio/wav`, `audio/amr`, or `audio/mpga`. Limit: `30 MB`."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "User identifier."
|
|
}
|
|
}
|
|
},
|
|
"AudioToTextResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"text": {
|
|
"type": "string",
|
|
"description": "Output text from speech recognition."
|
|
}
|
|
}
|
|
},
|
|
"TextToAudioRequest": {
|
|
"type": "object",
|
|
"description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.",
|
|
"properties": {
|
|
"message_id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Message ID. Takes priority over `text` when both are provided."
|
|
},
|
|
"text": {
|
|
"type": "string",
|
|
"description": "Speech content to convert."
|
|
},
|
|
"user": {
|
|
"type": "string",
|
|
"description": "User identifier."
|
|
},
|
|
"voice": {
|
|
"type": "string",
|
|
"description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/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",
|
|
"description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play."
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
]
|
|
}
|